Guides

Tasks

Create asynchronous tasks, export large results, and understand how tasks are queued and limited.

Sometimes you need to get access to the full list of documents, the full list of your entities or any large result.
To do that, you can either make multiple requests using the Pagination or use an asynchronous task.

This asynchronous task will be faster than doing multiple requests.

The download urls are valid for the next 5 minutes.

You can only have one running export task at a time.

Task results are deleted after 1 week.

loop [Polling status] POST /[endpoint]/export Create task 202 Accepted {task_id} GET /tasks/{task_id}/status Task status Save results. Update status POST /tasks/{task_id}/download 200 OK {urls} Use the download urls to get the results Client API Task
Sequence diagram showing a successful export

Exporting a large result consists of three steps:

  1. Asking for a export task, using POST /[endpoint]/export.
  2. Polling the status of the task, using GET /tasks/{task_id}/status.
  3. Retrieving download urls, using POST /tasks/{task_id}/download.

Exports consists of one or multiple csv files. Columns order might change between releases.

Task queuing

Tasks that are not queued

Export tasks and universe ESG report tasks are dispatched immediately when you create them. They do not go through the queue described below.

The report generation queue

Some tasks - namely AI Report generation tasks - go through a queue, because generating a report has a real, limited capacity behind it.

AI Report tasks (esg_due_diligence, deal_screening, legal_screening, supplier_chain_screening, secondary_and_credit_screening, good_governance_screening) share a limited amount of capacity across all clients using the platform.

When you request one of these reports:

  • If there is enough capacity available, the task starts immediately.
  • Otherwise, the task is created with a pending status and stays in the queue until capacity frees up.

See Limitations for the exact number of tasks each client can run at once.

How queued tasks are picked

Whenever a running report task completes or fails, the queue is re-checked to see if a pending task can now start.

Pending tasks are considered smallest-first: a report covering fewer companies is picked before a larger one, since it frees up capacity again sooner. Among tasks of the same size, the pick is randomized rather than strictly first-in-first-out. This is deliberate: without it, a client that queues many similarly-sized reports at once could occupy every slot that frees up, blocking other clients from ever being served while that queue is being worked through.

Task status

StatusMeaning
pendingThe task has been created but is waiting in the queue for capacity to become available. Tasks that are not subject to the queue never stay in this state.
startingThe task has been dispatched and execution is being initialized.
runningThe task is actively being processed.
completedThe task finished successfully. Results can be retrieved, see the steps above or Generate an AI Report.
failedThe task could not be completed.

pending, starting, and running are all non-final states: you should keep polling GET /tasks/{task_id}/status until you reach completed or failed.