Sign in

v1

latestOpenAPI 3.0.32026-07-222085264.6 KB
Batch APIs

Get the status and download URLs for a batch job

Poll the current state of a batch job. The status moves pending → processing → completed or failed. When the job is completed, the response includes a download_url for the merged results file and download_urls for the same data split into parts; both are pre-signed links valid for 5 days. When the job is failed, error_message carries a human-readable reason.

Results files are gzipped JSONL (one record per line). Enrichment job records are wrapped in an {original_identifier, internal_id, data} envelope; search job records are flat and match the corresponding non-batch endpoint's record shape.

The x-api-version header is not required on this endpoint.

get/batch/{batch_id}

Path parameters

batch_idstring uuid required
Example:53ab686b-c054-496b-8baf-baff5ecc85cf

The batch job ID returned at submit time.

Response

Current state of the batch job, with download links when completed

batch_idstring uuid required

Unique ID of the batch job.

status'pending' | 'processing' | 'completed' | 'failed' required

Job lifecycle status. Moves pending → processing → completed or failed.

entitystring required

Entity type the job operates on (company or person).

actionstring required

Internal action name for the job (enrich, enrich_live, search, or search_live).

identifier_countinteger required

Number of identifiers submitted. Search jobs always report 1 (the query).

result_countinteger required

Number of records the job has produced so far. For completed jobs, this is the number of lines in the results file.

entities_requestedinteger required

Number of entities the job was asked to produce.

entities_fulfilledinteger required

Number of entities actually delivered. May be lower than entities_requested when some identifiers cannot be resolved; for search jobs it equals result_count and may exceed entities_requested.

created_atstring date-time nullable required

When the job was submitted (ISO 8601).

completed_atstring date-time nullable required

When the job finished (ISO 8601). null while the job is still pending or processing.

error_messagestring

Human-readable reason the job failed (for example, when the processing workflow could not be started). Present only when the job has an error.

download_urlstring uri

Pre-signed URL for the single merged results file (gzipped JSONL, one record per line). Present only for completed jobs. The real URL carries signed authentication query parameters (elided in the example) and stays valid for 5 days.

download_urlsstring[]

Pre-signed URLs for the same data split into part files, useful for streaming very large result sets. Present only for completed jobs that wrote results. The real URLs carry signed authentication query parameters (elided in the example) and stay valid for 5 days.

Example response

{
  "batch_id": "53ab686b-c054-496b-8baf-baff5ecc85cf",
  "status": "completed",
  "entity": "company",
  "action": "enrich",
  "identifier_count": 2,
  "result_count": 2,
  "entities_requested": 2,
  "entities_fulfilled": 2,
  "created_at": "2026-06-12T12:23:03.945900+00:00",
  "completed_at": "2026-06-12T12:23:15.993293+00:00",
  "download_url": "https://crustdata-batch-api-data.s3.amazonaws.com/53ab686b-c054-496b-8baf-baff5ecc85cf/output/results.jsonl.gz",
  "download_urls": [
    "https://crustdata-batch-api-data.s3.amazonaws.com/53ab686b-c054-496b-8baf-baff5ecc85cf/output/part-000.jsonl.gz"
  ]
}