Tasks

Create an asynchronous source task

Start a source task from settings. You do not need input rows or a destination collection. The API returns 202 Accepted with a task ID; save it to check status and read results.

Each active source or enrichment task in your account needs a different uniqueId. An active duplicate returns 409. Once a task finishes or becomes overdue, the same ID can start new work and consume credits again. Check history before retrying a lost creation response.

Set maxCredits to stop starting new work after a credit threshold. Work already underway can exceed it. If you omit the field, your account balance still applies. See source limits for request and output sizes.

Required permissions: enrichments:tasks:create

post/v1/sources/tasks

Authorizations

Authorizationstringheaderrequired

Use an account access token as Bearer <token>.

Get an access token ↗

Body

application/json · required

Additional properties are not allowed.

uniqueIdstringrequired

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

settingsobject

Validated against the requested source's settingsSchema from catalog discovery.

Show child attributes

object

Validated against the requested source's settingsSchema from catalog discovery.

Additional properties are supported.

maxCreditsstring

Stop starting new work after this credit threshold. Work already underway can exceed it. Omit for no task-specific limit; your account balance still applies. "0" stops after the first paid completion. Values round upward to hundredth-credit precision. Read credits.used for actual usage.

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

sourceIdstringrequired

An authorized source ID from catalog discovery.

Response

202409413422429503

New task stored durably and all queue batches accepted

202 · 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

Create an asynchronous source task

PythoncURLJavaScriptPHPGo

import requests

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

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

payload = {
    "sourceId": "instagram-source",
    "uniqueId": "instagram-followers-20261009",
    "settings": {
        "profiles": "example_profile",
        "scrapingType": "followers",
        "limitPerProfile": 100
    }
}

response = requests.post(url, headers=headers, json=payload)

print(response.text)

Response · illustrative example

202409413422429503

{
  "@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"
  }
}