Bulks

List the jobs of a type, limit per page, sorted by job ID. Jobs are shared by all members of a workspace. Archived jobs are listed only with archived=true, and deleted jobs never.

Create a job from a list of values, data rows, or a CSV file (multipart). With data or file, each column is found from the header row unless you set its zero-based *_field_index. The options a type uses are listed in Bulk types; unknown parameters are ignored.

The job is pending until you launch it. With launch set to true, it starts right away; if it can't, it stays pending and data.message says why. A domain export (export) takes one domain, always starts, and needs a paid plan.

Nothing is charged until the first download; see Billing. You can create 15 jobs of a type a day (30 domain exports), and none while 2 jobs of the type are running; see Limits.

Get a job by ID, with its options in config, its results in metrics, and, once it is billed, the first result rows in preview.

Start a pending job; any other status, or an expired job, returns 409. The launch is refused with 429 while 2 jobs of the type are running, or when a kind of credit the job needs is used up. Nothing is charged at launch; see Billing. Follow the job with GET /bulk/{type}/{id}/progress or a webhook.

Get a job's status, progress, estimated time left, and results so far. The fields are at the top level of the response, not in data. Poll until status is completed, failed, or cancelled, or use a webhook instead.

Download a result file of a completed job as CSV. file selects it: full (the default), valid, or not_found. A job without a file of that kind returns 404, and a job past its expired_at returns 409.

The first successful download charges the job's credits, shown in metrics.credits; later downloads of any file are free. If your balance is lower than the cost at the first download, the response is 429 and nothing is charged. See Billing.

Each job can be downloaded 25 times a day, and a domain export 30 times.

Get the credits a job costs, and whether your balance covers them. Before the job completes, basis is upper_bound: the cost if every row returned the maximum. Once it completes, basis is exact: what the first download charges.

List a job's events, oldest first: creation, launch, start, end, retries, downloads, renames, archiving, and webhook deliveries.

Cancel a pending job: its status becomes cancelled, and you can retry it later. Only a pending job can be cancelled; any other status returns 409.

Run a failed or cancelled job again from its input, with the same options. Its results and metrics are reset, retry_count goes up by one, and the job is launched. It returns 409 when the job has another status, has expired, or its input is no longer stored, and 429 like PUT /bulk/{type}/{id}.

Rename a job.

Archive a completed, failed, or cancelled job: it leaves the default list and appears with archived=true. Restore it with PUT /bulk/{type}/{id}/restore. Other statuses, and an archived job, return 409.

Move an archived job back to the default list. A job that isn't archived returns 409.

Delete a job. It no longer appears in lists and its routes return 404.

List every bulk type with its input fields and the header names detected for them, its options, row limit, daily limits, result files, and metrics distributions.

Get the bulk activity of your account, or of your workspace: jobs created by status, rows processed, results, and credits billed, in total, per type, and per day. The period is the last 30 days unless you set from and to, and is at most one year.

Get the key your bulk job events are signed with. It is created on first use, or when you first create a job with webhook_url. See Bulk job events.

Replace the key your bulk job events are signed with. The old key stops working at once, including for events of jobs that are already running.