Before using these instructions, check operation availability and compatibility.
hbd campaign records pull reads the records one CampaignA developer's data-production project and its settings has delivered into one subscription. It always replays from the first record, so it never moves the subscription's incremental reading position. The Campaign filter can only narrow what the subscription already authorizes: for a priced subscription that is the range already acquired, and in every case it is delivered records, not all of the Campaign's submissionsThe record created when work is submitted. Confirm that hbd --help --json lists the command in your build; with a build that lacks it, page through the HTTP data API.
Credential and a first page
The command needs a full organizationThe Developer-side unit that holds Campaigns, data access, and funds API Key with data access to the subscription. A session from hbd auth login is refused. A Key with only the Data grant can still run hbd capabilities; it reports the Campaign API catalog as unavailable, which has no effect on this command. Set HB_API_KEY and HB_SUBSCRIPTION_ID as in Get your first authorized data, then pass the Key to this one command:
printf 'Campaign ID: '
read -r HB_CAMPAIGN_ID
HB_API_KEY="$HB_API_KEY" hbd campaign records pull "$HB_CAMPAIGN_ID" \
--subscription "$HB_SUBSCRIPTION_ID" \
--limit 5 --jsonWithout --all, the command reads one page and returns data.next_cursor. --limit sets the page size: 50 by default, 200 at most. The command takes exactly one Campaign ID.
When this Key reads the Campaign through exactly one subscription, you can leave --subscription out. The command finds that subscription, names it in a notice, and returns it as data.subscription_id. With several, it reads nothing and answers SUBSCRIPTION_AMBIGUOUS; hbd campaign subscription list <campaign-id> lists them, newest first. A continuation with --cursor always names its subscription.
Export all pages
--all follows the cursor until the server reports no more records. Send the result to a private directory:
HB_EXPORT_DIR="$(mktemp -d)"
printf 'Export directory: %s\n' "$HB_EXPORT_DIR"
HB_API_KEY="$HB_API_KEY" hbd campaign records pull "$HB_CAMPAIGN_ID" \
--subscription "$HB_SUBSCRIPTION_ID" \
--limit 200 --all --json > "$HB_EXPORT_DIR/campaign-records.json"
printf 'Exit code: %s\n' "$?"The records are in data.items. Treat the file as a complete export only when both checks pass: the exit code is 0, and data.complete is true.
data field | Meaning |
|---|---|
items | The records this command read, in the order the server returned them. |
count | The number of records in items. |
pages_read | The number of pages this command requested. |
has_more | Whether the server still reported more records when the command stopped. |
next_cursor | Where a later command can continue, or null. |
complete | true only when the command started at the first record, without --cursor, and reached the last page. |
pagination_stop_reason | null, or the reason an --all read stopped early. |
Export one JSON object per line
If hbd campaign records pull --help lists --jsonl, use it to write one delivered record per line to standard output. In the export command above, replace --json with --jsonl and save the output as campaign-records.jsonl. Each line has the same fields as an entry in data.items from the JSON envelope. Add --quiet to suppress progress counters.
After writing the rows, the command prints a records-checkpoint line to standard error. Parse the JSON object after the prefix for count, pages_read, complete, has_more, next_cursor, pagination_stop_reason, campaign_id, and subscription_id. A complete export requires exit 0 and complete: true. A read started with --cursor is a slice, even if it reaches the last page.
When an --all walk stops early at a pagination limit or a bad cursor, exit 1 accompanies the rows already read and a partial checkpoint. Continue with its next_cursor and subscription_id if it supplies a cursor. A request failure before the walk finishes leaves standard output empty. Keep the exit code and checkpoint with the export.
Complete and partial results
The examples show legacy v1 output, selected with HB_CLI_ENVELOPE_VERSION=v1. The new default v2 envelope also has a top-level nextAction field. The examples omit data.items, context, and notices; the identifiers are illustrations.
{
"apiVersion": "humanbased.cli/v1",
"command": "campaign.records.pull",
"requestId": "e9dc2862-d165-44ce-b54a-42111284bd40",
"context": {
"profile": null,
"apiOrigin": "https://api.humanbased.ai",
"organizationId": "10571000020000000001"
},
"data": {
"subscription_id": "784210003001",
"campaign_id": "784210001001",
"count": 1342,
"pages_read": 7,
"has_more": false,
"next_cursor": null,
"complete": true,
"pagination_stop_reason": null
},
"notices": [],
"error": null
}A partial export exits 1. It still carries the records read so far, and it names why it stopped:
{
"apiVersion": "humanbased.cli/v1",
"command": "campaign.records.pull",
"requestId": "e9dc2862-d165-44ce-b54a-42111284bd40",
"context": {
"profile": null,
"apiOrigin": "https://api.humanbased.ai",
"organizationId": "10571000020000000001"
},
"data": {
"subscription_id": "784210003001",
"campaign_id": "784210001001",
"count": 100000,
"pages_read": 500,
"has_more": true,
"next_cursor": "example-opaque-cursor",
"complete": false,
"pagination_stop_reason": "item_limit"
},
"notices": [],
"error": {
"code": "PAGINATION_INCOMPLETE",
"httpStatus": null,
"message": "The --all walk stopped while the server still reported more pages. The partial data and a continuation cursor, when available, are included.",
"retryable": false,
"nextAction": null,
"details": null
}
}pagination_stop_reason | What happened | What to do now |
|---|---|---|
page_limit | The command read 1,000 pages. At the default page size of 50, that is 50,000 records. | Continue from next_cursor. Pass --limit 200 to read more records per run. |
item_limit | The command read 100,000 records. | Continue from next_cursor. |
missing_cursor | The server reported more records and returned no cursor. | next_cursor is null, so this file has no safe place to continue from. Keep it for diagnosis and run the export again from the first record. |
repeated_cursor | The server returned a cursor this command had already used. | next_cursor is null. Never resubmit the repeated cursor. Run the export again from the first record or from an earlier cursor you saved, and contact support@humanbased.ai if it repeats. |
Continue a partial export
Continue only when data.next_cursor is a string. Copy its value without the JSON quotes:
printf 'Part number, 2 for the first continuation: '
read -r HB_PART
printf 'Next cursor: '
read -r HB_CURSOR
HB_API_KEY="$HB_API_KEY" hbd campaign records pull "$HB_CAMPAIGN_ID" \
--subscription "$HB_SUBSCRIPTION_ID" \
--cursor "$HB_CURSOR" \
--limit 200 --all --json > "$HB_EXPORT_DIR/campaign-records-$HB_PART.json"
printf 'Exit code: %s\n' "$?"One run reads at most 100,000 records, so a large export needs several continuations. Save each one to its own file: part 2, then part 3, and so on. A continuation saved over an earlier file loses that file's records.
A continuation holds only the records after the cursor. Its data.complete stays false even when it reaches the last page and exits 0. The whole export is the first file's data.items followed by the data.items of each continuation, with the same Campaign and subscription in every command.
Protect the output
| Part of the export | What it means for you |
|---|---|
| Record content | data.items[].data is written exactly as delivered, including any value that happens to look like a credential. Store the file under the same rules as the source data. |
| Numbers | Numbers inside record content keep their original digits, including integers beyond JavaScript's safe range and long decimals. Use a parser that preserves them when your values need that precision. |
| Temporary file | While it reads, the CLI stages the records in a file in the system temporary directory that only the current user can read, and deletes it when the command ends. Leave enough free space there for the whole export. |
| Interrupted output | When the pipe closes or the destination fills up, the command exits with a non-zero code and reports the failure on standard error. A JSON file that was already partly written is incomplete: discard it and run the export again. |
Errors
Exit code and error.code | Cause | What to do now |
|---|---|---|
1, PAGINATION_INCOMPLETE | An --all read stopped while more records remained. | Read data.pagination_stop_reason and continue as described above. |
2, INVALID_ARGUMENT | The Campaign ID is blank or a comma-separated list, an ID or cursor looks like a credential, or a --cursor came without its --subscription. Nothing was sent. | Pass one Campaign ID and the real identifiers. Supply the Key only through HB_API_KEY or --token-stdin. |
2, SUBSCRIPTION_AMBIGUOUS | --subscription was left out, and this Key reads the Campaign through several subscriptions. Nothing was read. | Pick one from hbd campaign subscription list <campaign-id> and pass it with --subscription. |
3 | No usable credential: the Key is missing, malformed, expired, or revoked, or a sign-in session was used. | Supply a full organization API Key. |
4 | The Key has no data access, or the subscription is outside its scope or organization. | Check the Key's Data grant in Create and use an API Key. |
4, SUBSCRIPTION_NOT_BOUND | --subscription was left out, and this Key reads the Campaign through no subscription. Nothing was read. | Check the Campaign ID. For one of your organization's own Campaigns, create a Key with Campaign access for it. |
6 | The service was unavailable, or the output could not be delivered. | Run the same command again; a replay charges nothing and moves no position. |
For API operations and grants, see Campaign API. To hand one bounded read to an agent, see Use an agent with Humanbased.