Tasks

Get task status

Check a source task's status, generated-object count, credits used, and error details. Use the task ID returned at creation.

Check every few seconds until status is completed, failed, or stopped, then read links.results. A successful task can return no objects; failed and stopped tasks can keep partial results.

Required permissions: enrichments:tasks:read

get/v1/sources/tasks/{taskId}

Authorizations

Authorizationstringheaderrequired

Use an account access token as Bearer <token>.

Get an access token ↗

Path parameters

taskIdstringrequired

Copy the task's returned @id unchanged. New tasks use a 32-character hexadecimal UUID4; existing IDs with the task_ prefix remain supported.

pattern: "^(?:task_)?[a-f0-9]{32}$"

Response

Task metadata without raw inputs

200 · application/json

@idstringrequired

@typestringrequired

const: "SourceTask"

uniqueIdstringrequired

pattern: "^[A-Za-z0-9_-]+$"minLength: 1maxLength: 128

statusstringrequired

The task is active while queued, running, or stop_asked. Read results after completed, failed, or stopped. Reaching maxCredits can finish with partial results. A stop ends in stopped unless the task also fails.

Allowed values: "queued", "running", "stop_asked", "completed", "failed", "stopped"

createdAtstringrequired

format: "date-time"

startedAtstring | nullrequired

format: "date-time"

finishedAtstring | nullrequired

format: "date-time"

progressobjectrequired

Number of generated objects recorded so far.

Show child attributes

resultsintegerrequired

minimum: 0

creditsobjectrequired

Show child attributes

usedstringrequired

pattern: "^[0-9]+(\\.[0-9]+)?$"

maxstring | nullrequired

Null when the caller omitted maxCredits (no limit).

pattern: "^[0-9]+(\\.[0-9]+)?$"

linksobjectrequired

Show child attributes

object

Additional properties are supported.

kindstringrequired

const: "source"

sourceIdstringrequired

errorobject | nullrequired

Null while the task is active or successfully completed. On failure, includes error details and a traceId when available. A stopped task can keep an error that occurred before it stopped.

Show child attributes

reasonstringrequired

Stable reason for a failed task.

Allowed values: "dispatch_failed", "deadline_exceeded", "worker_failed", "enrichment_failed", "credits_error"

codestringrequired

messagestringrequired

traceIdstring | nullrequired

Get task status

import requests

url = "https://api.datablist.com/v1/sources/tasks/<taskId>"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

Response · illustrative example

{
  "@id": "string",
  "@type": "SourceTask",
  "uniqueId": "string",
  "status": "queued",
  "createdAt": "2024-07-29T15:51:28.071Z",
  "startedAt": "2024-07-29T15:51:28.071Z",
  "finishedAt": "2024-07-29T15:51:28.071Z",
  "progress": {
    "results": 0
  },
  "credits": {
    "used": "string",
    "max": "string"
  },
  "links": {},
  "kind": "source",
  "sourceId": "string",
  "error": {
    "reason": "dispatch_failed",
    "code": "string",
    "message": "string",
    "traceId": "string"
  }
}