# Export every delivered record


> Before using these instructions, check [operation availability and compatibility](/api/compatibility).

`hbd campaign records pull` reads the records one Campaign 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 submissions. Confirm that `hbd --help --json` lists the command in your build; with a build that lacks it, page through the [HTTP data API](/api/api-data).

## Credential and a first page

The command needs a full organization 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](/api/api-data), then pass the Key to this one command:

```sh
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 --json
```

Without `--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:

```sh
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.

```json
{
  "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:

```json
{
  "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](mailto: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:

```sh
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](/api/api-auth). |
| `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](/api/campaign-api). To hand one bounded read to an agent, see [Use an agent with Humanbased](/api/agent-access).
