Get your first authorized data

Retrieve a small page of delivered records, inspect its fields, and understand what you may do with it.

You can use an existing subscription; you do not need to create a campaign first.

This guide uses the HTTP API. The examples target production and require credentials and a subscription for that environment. They retrieve existing records with from=beginning, so they do not advance your organization's incremental reading position.

Before you start

You need a terminal with curl and Python 3, plus:

An account in the organization that owns the subscription.
An active Subscription ID and a full organization API Key with access to it.
Permission under the data's applicable terms to retrieve and use the records for your intended purpose.
At least one eligible delivered record. For a priced subscription, this guide can replay only the range that the subscription has already acquired.

A Subscription ID selects the data. An API Key proves which organization and subscription scope your program can access. They are different values; a Campaign ID cannot replace a Subscription ID.

Check your intended use. Seeing a dataset or reviewing a submission in the portal does not grant permission to retrieve, redistribute, or train on it. Confirm the applicable terms with your organization before sending a request.

1. Select your organization and subscription

Open the production Developer portal's API Keys page. You can also open the account-and-organization menu at the bottom left of the portal and select API Keys.

Check the organization name before continuing. Under Pull data with your API key, find Pull from and select the intended source. If there is only one source, its name may appear without a dropdown. Copy its subscription_id.

If the page says No subscription yet, stop here. For your organization's own campaign, an organization member can select an eligible campaign when creating a key; the platform creates or reuses its subscription. For external data, arrange the required subscription and usage terms first. Creating a key does not purchase access.

2. Obtain a key for that subscription

Any member of your organization can create a key on this page. A data-read key can be scoped to any campaign your organization owns that is in a state that serves data; draft and archived campaigns are not offered. This does not depend on your editing rights for the campaign. Those rights limit only keys that carry campaign write access.

If you already have a full key, check its Scope, Status, and Expires. An Active label does not override an expired date.

To create one:

Select Create API Key and enter a recognizable Name, such as “Evaluation data read”.
Choose an expiry under Expires.
Under Permissions → Data, turn on data access. The form starts with no permission selected and does not create a key until you choose one.
Decide how far the key reaches. Left as it is, the Data grant covers every subscription your organization has now or creates later. For this guide, expand Limit this key to specific subscriptions or campaigns and select the subscription you identified above under Subscription access. To read one of your organization's own campaigns, select it under Campaign access instead. Opening the picker without selecting anything keeps the organization-wide grant.
Review the organization and scope, complete any required agreement step, and select Create key.
Copy the full key from Your new API key and store it in your organization's approved secret store. It is shown only once.

If a campaign is marked partial, its existing subscription has a narrower scope. Reusing it does not expand that scope. Ask the organization administrator to resolve an access mismatch instead of repeatedly creating keys.

3. Prepare a small read

Run these commands in bash or zsh. Enter your key at the prompt; it will not be displayed or included literally in the command history. Do not paste it into an agent conversation, screenshot, source file, or browser URL. The setup starts with unset HB_API_KEY because read keeps the export attribute of a variable that was already exported, and the key would otherwise reach every process you launch from this shell.

export HB_API_URL='https://api.humanbased.ai'
unset HB_API_KEY
printf 'API Key: '
read -rs HB_API_KEY
printf '\nSubscription ID: '
read -r HB_SUBSCRIPTION_ID

The API host, subscription, and credential must belong to the same environment. Use the production portal and its matching values for the request below. For a staging integration, use https://api.staging.humanbased.ai and credentials issued for that environment.

4. Retrieve the first page

The following request asks for up to five records. It saves the response in a new, private local directory and prints the HTTP status. The directory name is shown so you can find the file later.

HB_DOWNLOAD_DIR="$(mktemp -d)"
printf 'Response directory: %s\n' "$HB_DOWNLOAD_DIR"
curl --silent --show-error --get "$HB_API_URL/v1/live/pull" \
  --header "Authorization: Bearer $HB_API_KEY" \
  --data-urlencode "subscription_id=$HB_SUBSCRIPTION_ID" \
  --data-urlencode 'from=beginning' \
  --data-urlencode 'limit=5' \
  --output "$HB_DOWNLOAD_DIR/first-page.json" \
  --write-out 'HTTP %{http_code}\n'

Keep this read in replay mode. Include from=beginning. Omitting it switches to incremental delivery, which moves a position shared by every consumer of this subscription and may incur a charge. Do not remove it simply to make an empty result nonempty.

5. Verify what you received

Open the saved JSON locally:

python3 -m json.tool "$HB_DOWNLOAD_DIR/first-page.json"

A successful response has success: true and errorCode: 0. The records are in data.items; data.count is the number on this page.

For each record, inspect:

Field	What to check
`submission_id`, `task_id`, `campaign_id`	The record's identifiers and source context. Keep IDs as strings.
`template_id`	The template associated with the delivered content; an empty value means it is unknown.
`data`	The delivered fields. These are already JSON, not a second JSON-encoded string.
`quality_grade`, `quality_score`	The recorded grade and its mapped score; neither proves improvement in your model.
`created_at`	The original submission time, not this request's completion time.

The delivered fields may be mapped from the original submission. Use the agreed output schema; do not assume the portal's review form and data have identical field names.

This request is a page, not a complete export. When data.has_more is true, another page is available. Even on the last page, “complete” means the current readable subscription scope, not every campaign submission or an immutable dataset snapshot.

6. Continue only when you need more

For another page, copy the latest data.next_cursor value without its surrounding JSON quotes. Keep the same subscription, mode, and any filters.

printf 'Next cursor: '
read -r HB_CURSOR
HB_NEXT_PAGE="$(mktemp "$HB_DOWNLOAD_DIR/page.XXXXXX")"
printf 'Response file: %s\n' "$HB_NEXT_PAGE"
curl --silent --show-error --get "$HB_API_URL/v1/live/pull" \
  --header "Authorization: Bearer $HB_API_KEY" \
  --data-urlencode "subscription_id=$HB_SUBSCRIPTION_ID" \
  --data-urlencode 'from=beginning' \
  --data-urlencode 'limit=5' \
  --data-urlencode "cursor=$HB_CURSOR" \
  --output "$HB_NEXT_PAGE" \
  --write-out 'HTTP %{http_code}\n'

Continue until has_more is false, saving each page before moving on. Treat the cursor as opaque; never substitute a Submission ID or construct one. If a page claims more results but supplies no next cursor, stop and retain the response for investigation.

To export every delivered record of one campaign in a single command, use the hb CLI: see Export every delivered record.

If you cannot retrieve records

Result	Next action
`401`	Check that you supplied the full key, that it has not expired or been revoked, and that the header starts with `Bearer` .
`403`	Check the key's data-delivery access and subscription scope. A different organization's key is not a workaround.
`404` or “Subscription not found”	Check the subscription and environment with your administrator. Do not substitute a Campaign ID.
`success: true`, but `items: []`	Check delivery status, subscription filters, and the already-acquired range of a priced subscription. Accepted campaign work may still be awaiting reward settlement or delivery.
`400` or `422`	Compare parameters with the API reference, including the limit and reading mode.
`503` or a network interruption	Retry this replay request after a short delay. Save only a complete successful response; a partial file is not a valid page.

Zero-priced subscriptions can replay eligible records beyond their incremental reading position. Priced subscriptions replay only their already-delivered range. Replay returns receipt: null; this does not mean the underlying data has no price or usage restrictions.

For help, contact hello@humanbased.ai with the environment, request time, HTTP status, and sanitized error. Never include the full key or private record content.

You have completed this guide when

You have a saved, successful response containing at least one record, can identify its source and delivered fields, and have confirmed the terms for your intended use. An empty success response proves that the request worked, not that you obtained data.

Record the retrieval time, subscription, applicable terms, and source identifiers alongside your local copy. Keep that copy in storage appropriate for the data. The response does not itself contain a complete license or a frozen collection version.

Next, read the data-retrieval API reference for pagination and incremental delivery, or give an agent a bounded read task. Before using the records to improve a model, establish a baseline and a separate held-out evaluation. How Humanbased works explains that larger loop.