Skip to main content

Tasks

Create a source task with sourceId, uniqueId, and settings. It generates JSON objects without input rows or a destination collection. You cannot change its settings after creation, and only your account can access it.

The returned @id is the task ID used in status, stop, 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.

Declared settings validate against the source's settingsSchema. Additional keys are accepted and passed through unchanged, subject to the same JSON safety, nesting, and request-size limits.

Task limits​

Source creation requests accept up to 10 MiB of JSON and have no input array. Sources and enrichments share a target limit of 20 active tasks per account, including queued and stopping tasks. Simultaneous requests can occasionally exceed it. Tasks have a 24-hour execution deadline. See request, output, and pagination limits.

Task states​

Tasks use queued, running, stop_asked, completed, failed, and stopped. Check status until it is completed, failed, or stopped, then read results. progress.results counts generated objects; a successful task can return zero objects. If the task failed, error explains why. Errors are reported for the task, not for each generated row.

Credit limits​

Use the same account credits as the web app. An optional maxCredits decimal string is a best-effort stop threshold, not a guaranteed price cap. Already started work can finish and exceed it. Omit the field for no task-specific budget; your account balance still applies. An explicit "0" allows zero-credit work and stops after the first paid completion. Actual usage is in credits.used.

Task reference​

Shared lifecycle and safe retries​

Each active source or enrichment task in your account needs a different uniqueId. If a creation response is lost, check both histories before sending another POST. Once the original task finishes or becomes overdue, the same ID can start new work and consume credits again. See the quickstart.

The execution deadline is 24 hours. Task metadata and generated results are retained for 90 days after completion, failure, or a stop. Stop requests do not undo spent credits or remove completed objects. Repeating a stop is safe. The shared cancellation timing applies to sources too.

Source tasks have no inputs endpoint. Looking up a source task through an enrichment route returns 404. See Get tasks results and limits/errors.