Skip to main content

Tasks

An enrichment task contains settings, one to 10,000 input rows, progress, outcomes, and credit usage. A source task uses the same lifecycle but generates rows from settings instead of accepting inputs.

The returned @id is the task ID used in status, stop, inputs, and results URLs. New tasks use a 32-character hexadecimal UUID4, such as 00000000000040008000000000000001. Existing IDs starting with task_ remain valid. Copy the complete returned ID unchanged; do not add or remove a prefix. This ID is separate from the uniqueId you choose when creating a task.

Task reference​

Source operations have their own task reference.

Validate requests against the catalog​

Before creating a task, fetch its definition from the catalog. The API validates:

  • enrichment input data against inputSchema;
  • declared settings fields against settingsSchema;
  • required fields, types, formats, and allowed values;
  • the request and task limits documented for that catalog entry.

Additional settings keys are accepted and passed through unchanged. Declared fields still enforce their types, choices, and required values. All settings remain subject to JSON safety, nesting, and request-size limits.

You cannot change settings or inputs after creating a task. To read what you submitted, use links.inputs and follow its result pages.

Choose uniqueId values carefully​

Choose a uniqueId for each task, such as company-import-part-1. It prevents you from starting two active tasks with the same ID in one account.

If that ID belongs to an active task whose deadline has not passed, creation returns 409 DuplicateApiTask. Once the task completes, fails, stops, or becomes overdue, you can reuse the ID. Reusing it starts new work, even if the settings and inputs are identical.

If a creation response is lost, read task history and look for your uniqueId before retrying. There is no uniqueId history filter, so check each page. Source and enrichment tasks share these IDs; check both histories if you use both APIs. Sending another POST can repeat paid work.

Task limits​

Each creation request accepts 1–10,000 inputs, with at most 16 KiB per input's data object and 10 MiB for the complete request. The service splits inputs into execution batches automatically. Enrichment and source tasks share a target limit of 20 active tasks per account, including queued and stopping tasks. Simultaneous requests can occasionally exceed this target. See all limits and batching guidance.

Task states​

Tasks move through these states:

  • queued: accepted and waiting to start.
  • running: execution is in progress.
  • stop_asked: cancellation was requested; already-started work can finish.
  • completed: execution finished, including tasks stopped by a credit budget.
  • failed: execution ended because of a task-level error.
  • stopped: cancellation completed.

error is null while a task is active or successfully completed. A failed task includes reason, code, message, and a traceId when available. A stopped task can also include an error if work failed before it stopped. See errors.

Credit limits​

Omit maxCredits to run without a task-specific credit limit. Your account still needs enough available credits for paid work. To set a limit, send a nonnegative decimal string such as "10". Credit values use hundredth-credit precision; a positive fraction below one hundredth rounds up, so 0.001 becomes 0.01.

maxCredits stops new batches once recorded usage reaches the threshold. Inputs that have not started become skipped with MAX_CREDITS_REACHED.

It is not a hard spending cap: work already underway can finish and exceed it. An explicit "0" allows free work, but the first paid completion is still charged before the task stops.

Always use the task and result credits fields as the record of actual usage.

Stop a task​

Request cancellation through the task's stop URL, for example:

http
POST /v1/enrichments/tasks/{taskId}/stop

Work already underway, can still finish. Inputs that have not started become skipped with TASK_STOPPED.

Check status until the task is completed, failed, or stopped. You can safely repeat a stop request, even after the task has finished.

If work stops reporting progress, cleanup can finish the cancellation after 15 minutes of inactivity, or 45 minutes for long-running work that cannot be interrupted. Cleanup scheduling can add delay, so these are not guaranteed stop times.

History, cursors, and retention​

List enrichment history at GET /v1/enrichments/tasks, filtering by status or enrichmentId. List source history at GET /v1/sources/tasks, filtering by status or sourceId. Both list newest tasks first. Pass nextCursor unchanged to read the next page; do not parse or build it yourself.

Tasks can run for up to 24 hours. Their metadata, inputs, and results are kept for 90 days after completion, failure, or a stop. After that, the task and its data return 404. Save any results you need to keep longer.