> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sixtyfour.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Async Jobs

> Follow long-running lookups, read their results and download files.

A Job saves an operation's ID, status and results so you can follow work after your request returns. Save its `job_id` to check progress and read results without starting the work again.

| Step | Request | Output |
| - | - | - |
| Start | Contacts, Intelligence, Age Verification, Search, Workflow or Export request | A Job |
| Poll | `GET /v1/jobs/{job_id}` | Current Job and result or error |
| Read items | `GET /v1/jobs/{job_id}/items` | Saved item page and `next_cursor` for Jobs with item results |
| Download Workflow output | URLs in the Job's `result` | Files produced by the Workflow's blocks |

The [Quick Start](https://docs.sixtyfour.ai/api-quick-start.md) finds one work email. [Batch Processing](https://docs.sixtyfour.ai/guides/batch-processing.md) covers files and lists.

## Start and wait

Search, Find Contacts, Reverse Lookup and Intelligence requests accept `wait_seconds` from 0 to 20 (default 5). Age Verification and Workflow runs accept it too; a Workflow run defaults to 0. It sets how long your request waits for the Job to finish. It does not limit how long the Job runs.

Use `0` to skip waiting for completion. A positive value gives short Jobs time to finish before the request returns. Reaching the wait limit does not cancel work; the Job continues in the background.

| HTTP status | Meaning |
| - | - |
| `200` | Finished. Read the result or error. |
| `202` | Still running. Poll the URL in `Location` after `Retry-After` seconds. |

Polling `GET /v1/jobs/{job_id}` returns HTTP `200` when you read the Job successfully, even while it is running. Check `status`, not the HTTP status, to decide whether to keep polling.

```json theme={null}
{
  "job_id": "job_3f8b2c1e-9d4a-4c1b-8e2f-6a7b5c4d3e21",
  "operation": "people.contacts",
  "status": "running",
  "created_at": "2026-11-13T10:00:00Z",
  "next_poll_after": 5,
  "counts": { "total": 1, "succeeded": 0, "failed": 0, "pending": 1 },
  "charge_credits": 0.0
}
```

Store IDs exactly as returned. Do not extract parts or rebuild them. Jobs use `job_`, files use `file_`, and lists use `list_`.

## Polling

| Status | Meaning | Continue polling |
| - | - | - |
| `queued` | Accepted, waiting to start | Yes |
| `running` | Work is in progress | Yes |
| `succeeded` | Work finished successfully | No |
| `failed` | Work ended with an error | No |
| `canceled` | Work was canceled | No |

Set `JOB_ID` to the ID returned by a start request. Replace `YOUR_API_KEY` with your API key. cURL also requires `jq`.

```bash cURL theme={null}
API=https://api.sixtyfour.ai
DELAY=5
while true; do
  sleep "$DELAY"
  JOB=$(curl --fail-with-body -sS "$API/v1/jobs/$JOB_ID" -H "x-api-key: YOUR_API_KEY") || exit 1
  echo "$JOB"
  case "$(echo "$JOB" | jq -r .status)" in succeeded|failed|canceled) break ;; esac
  DELAY=$(echo "$JOB" | jq -r '.next_poll_after // 5')
done
```

```python Python theme={null}
import os
import time
import requests

API = "https://api.sixtyfour.ai"
headers = {"x-api-key": "YOUR_API_KEY"}
delay = 5
while True:
    time.sleep(delay)
    response = requests.get(f"{API}/v1/jobs/{os.environ['JOB_ID']}", headers=headers)
    response.raise_for_status()
    job = response.json()
    print(job)
    if job["status"] in ("succeeded", "failed", "canceled"):
        break
    delay = job.get("next_poll_after") or 5
```

```javascript JavaScript theme={null}
const API = "https://api.sixtyfour.ai";
const headers = { "x-api-key": "YOUR_API_KEY" };
let delay = 5;
let job;
while (true) {
  await new Promise(resolve => setTimeout(resolve, delay * 1000));
  const response = await fetch(API + "/v1/jobs/" + process.env.JOB_ID, { headers });
  if (!response.ok) throw new Error(await response.text());
  job = await response.json();
  console.log(job);
  if (["succeeded", "failed", "canceled"].includes(job.status)) break;
  delay = job.next_poll_after ?? 5;
}
```

## Job status and item status

| Field | Scope | What to check |
| - | - | - |
| `Job.status` | The whole operation | Whether to keep polling and whether execution finished successfully. |
| `JobItem.status` | One item from `/items` | Whether that item's `result` is available or its `error` explains a failure. |

A succeeded Job can contain failed items. A failed Job can still have successful items; keep those results before deciding whether to submit replacement work. Contact fields such as `email_status` describe the answer, not execution: `NOT_FOUND` does not mean the lookup Job failed.

### Counts

`counts` reports input size, progress or saved item counts when available. Contacts and Intelligence know the input count when you send records directly. File-based requests and Search do not always know it at the start. Finished Jobs include counts when their saved items are readable. A missing or null `counts` means unavailable, not zero.

| Field | Meaning |
| - | - |
| `total` | Items tracked by the Job. |
| `succeeded` | Items that finished successfully. |
| `failed` | Failed or canceled items. |
| `pending` | Queued or running items. |

Contacts and Intelligence count input records; Search counts retained profiles, not the requested `max_results`. Counts do not measure credits. For an export's row count or a list's size, read the file's `row_count` or the list's `size` rather than assuming every Job counts data rows.

## Read every item

`GET /v1/jobs/{job_id}/items` accepts `page_size` from 1 to 1,000, default 100, and an opaque `cursor`. Pass each `next_cursor` unchanged to the next request; stop when it is null.

```json theme={null}
{
  "items": [
    {
      "index": 0,
      "custom_id": null,
      "input": {
        "name": "Saarth Shah",
        "company": "Sixtyfour"
      },
      "status": "succeeded",
      "result": {
        "name": "Saarth Shah",
        "company": "Sixtyfour",
        "email": "saarth.work@example.com",
        "email_status": "OK",
        "email_type": "COMPANY",
        "other_emails": []
      },
      "error": null
    }
  ],
  "next_cursor": null
}
```

Contacts and Intelligence items use the zero-based input-record position as `index` and echo the record's `custom_id` for matching. Search uses the result position, not an input-record position. Failed items carry `status: "failed"` and an error.

Reading items does not start new research.

## Browse Job history

`GET /v1/jobs` returns `{items, next_cursor}` for Jobs you can access. It accepts `status`, `operation`, `page_size` from 1 to 100, default 100, and `cursor`.

Jobs appear from newest to oldest. Keep filters unchanged between pages and stop when `next_cursor` is null.

### Captured charges

Every Job includes `charge_credits`: the credits charged so far, after refunds, when you read the Job. Credits held but not yet charged are not counted. The value can change after the Job finishes, so a finished Job does not mean billing is final. A `null` value means the charge is unknown or your team permissions withhold it. Legacy Jobs do not include this field.

```json theme={null}
{ "status": "succeeded", "charge_credits": 1.5 }
```

Verify Email bills in the background after its response and is unaffected by this field.

## Cancel work

`POST /v1/jobs/{job_id}/cancel` returns the Job with `cancel_requested_at`. Poll until the Job finishes. A finished Job is unchanged, and completed work remains billed.

## Export results

Send exactly one source to `POST /v1/exports`: `from.job_id` for a finished Job with item results or `from.list_id` for a ready list. Set `format` to `csv`, `json` or `ndjson`.

Exports contain successful item results. Empty results produce an empty export. Limits are 100 MB and 100,000 rows. CSV objects and lists use JSON text, booleans use `true` or `false`, and spreadsheet formulas are escaped.

For Workflow output, download the files in `result` directly, as shown in [Run a workflow batch](https://docs.sixtyfour.ai/guides/batch-processing.md#run-a-workflow-batch). Item results are not available for every Workflow. To save other formats, send `result_formats` when starting the Workflow run.

For a Job with item results, set `SOURCE_JOB_ID` to the finished source Job's ID.

**1. Start an export**

```bash cURL theme={null}
EXPORT=$(curl --fail-with-body -sS https://api.sixtyfour.ai/v1/exports \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d "{\"from\":{\"job_id\":\"$SOURCE_JOB_ID\"},\"format\":\"csv\"}")
JOB_ID=$(echo "$EXPORT" | jq -r .job_id)
echo "$EXPORT"
```

```python Python theme={null}
import os
import requests

export_response = requests.post("https://api.sixtyfour.ai/v1/exports",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"from": {"job_id": os.environ["SOURCE_JOB_ID"]}, "format": "csv"})
export_response.raise_for_status()
os.environ["JOB_ID"] = export_response.json()["job_id"]
print(export_response.json())
```

```javascript JavaScript theme={null}
const exportResponse = await fetch("https://api.sixtyfour.ai/v1/exports", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ from: { job_id: process.env.SOURCE_JOB_ID }, format: "csv" })
});
if (!exportResponse.ok) throw new Error(await exportResponse.text());
const exportJob = await exportResponse.json();
process.env.JOB_ID = exportJob.job_id;
console.log(exportJob);
```

**2. Poll the export Job**

The export request returns `202`. Run the [polling loop](#polling) with the export's `job_id`, not the source Job's ID. Continue only if the export reaches `succeeded`; otherwise inspect its error. Read the file ID from `result.output_file_id`.

**3. Download the file**

Call `GET /v1/files/{file_id}` to read the file's metadata. Then download its signed `download_url` with the same API key. Both requests require authentication. Do not follow redirects when sending credentials. The URL is valid for 15 minutes. Read the same file resource again to refresh an expired URL instead of rerunning research.

```bash cURL theme={null}
FILE_ID=$(echo "$JOB" | jq -r .result.output_file_id)
URL=$(curl --fail-with-body -sS "$API/v1/files/$FILE_ID" -H "x-api-key: YOUR_API_KEY" | jq -r .download_url)
curl --fail-with-body -sS --location --max-redirs 0 "$URL" -H "x-api-key: YOUR_API_KEY" -o results.csv
```

```python Python theme={null}
from pathlib import Path

file_response = requests.get(f"{API}/v1/files/{job['result']['output_file_id']}", headers=headers)
file_response.raise_for_status()
download = requests.get(file_response.json()["download_url"], headers=headers, allow_redirects=False)
download.raise_for_status()
if 300 <= download.status_code < 400:
    raise RuntimeError("Unexpected download redirect")
Path("results.csv").write_bytes(download.content)
```

```javascript JavaScript theme={null}
import { writeFile } from "node:fs/promises";

const fileResponse = await fetch(API + "/v1/files/" + job.result.output_file_id, { headers });
if (!fileResponse.ok) throw new Error(await fileResponse.text());
const file = await fileResponse.json();
const download = await fetch(file.download_url, { headers, redirect: "error" });
if (!download.ok) throw new Error(await download.text());
await writeFile("results.csv", Buffer.from(await download.arrayBuffer()));
```

> [card] [Try it](https://docs.sixtyfour.ai/api-reference/jobs/export-results.md)
>
> Open the Export Results API Reference playground.

## Idempotency keys

Send `Idempotency-Key` on start requests to retry without starting duplicate work. Generate a UUID v4 for each new operation. Save it with the request body before sending the request. The maximum key length is 255 characters.

```http theme={null}
Idempotency-Key: 6f1c2a9e-4b7d-4e3a-9c5f-2d8e1b0a7c43
```

1. The first request starts the work.
2. The same key and body return the same Job, without another charge. The response includes `Idempotent-Replayed: true`.
3. The same key with a different body returns HTTP `409` and `idempotency_key_reused`.

Keys are scoped to your organization and the action you start. JSON keys are remembered as long as the Job is available. CSV keys are remembered for 24 hours; the filename and contents must match. See [Handling Errors](https://docs.sixtyfour.ai/api-reference/errors.md) for retries.

## Records, items and rows

* A record is the person or company you send for processing.
* An item is an entry returned by `/items`, with an `input`, `status`, `result` and `error`.
* A row is an entry in an uploaded or downloaded data file.

## Results by Job type

| Job | Result |
| - | - |
| Single contact lookup or Intelligence request | The record's result in `Job.result` and in items. |
| Batch contact lookup or Intelligence | One item per input record. |
| Search | `search_id`, `count` and `output_file_id` in `Job.result`; profiles in items. |
| List | `list_id` and `size` in `Job.result`. |
| Age Verification | The date of birth, age, evidence and sources in `Job.result`. |
| Export | `output_file_id` in `Job.result`. |
| Workflow | Output files in `Job.result`, each with a `download_url`, `content_type` and `block_number`. |

## Webhooks

Set `webhook_url` on a Search, Contacts or Intelligence start request to receive callbacks. Verify signatures and deduplicate deliveries using [Outgoing Webhooks](https://docs.sixtyfour.ai/api-reference/webhooks/outgoing.md). Keep the returned `job_id` to poll or read items.

## Retention

Save results you need to keep. Reading items does not start research again; expired results return `items_not_available`. File download URLs expire; read the file resource again for a fresh URL.

## Related

* [Batch Processing](https://docs.sixtyfour.ai/guides/batch-processing.md)
* [Handling Errors](https://docs.sixtyfour.ai/api-reference/errors.md)
* [Credit Costs](https://docs.sixtyfour.ai/guides/credits-and-pricing.md)

> [!NOTE]
>
> For older Job status and callbacks, see [Legacy](https://docs.sixtyfour.ai/api-reference/legacy.md#job-status).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.