Tracking async work

Audience

Integrators waiting on document extraction or risk assessment completion.

What you'll accomplish

Know which resources to poll, what status values mean, and how often to poll.

Long-running operations return immediately with a resource id. Poll that resource until it reaches a terminal state.

Webhooks are not available. Polling is the supported pattern.

Poll intervals

Workload	Initial interval	Backoff	Stop when
Document extraction	2–5 seconds	×1.5 up to ~10 s	status is terminal
Risk assessment	5–10 seconds	Same	completed or failed

Example: poll at 3 s, then 5 s, then 8 s, then 10 s until done. Integrator routes are not rate-limited — see Errors — Rate limits.

Document extraction

After POST /projects/:projectPid/documents/upload-complete, save sourcePid.

Status flow

processing → connected   (success)
processing → error       (failed)

How to poll

1. GET /projects/:projectPid/documents
2. Find the row where pid matches sourcePid
3. Read status:
   • processing — poll again
   • connected — list artifacts at GET /projects/:projectPid/artifacts
   • error — read lastError

curl -sS 'https://api.air.thalus.ai/projects/<projectPid>/documents' \
  -H 'Authorization: Bearer <rawKey>'

While processing, optional fields: progress (0–100), currentStage.

Worked example

Time	status	Action
T+0 s	processing	Upload complete just returned
T+3 s	processing	progress: 20 — keep polling
T+8 s	processing	progress: 65 — keep polling
T+15 s	connected	List artifacts; start assessment

Risk assessments

After POST /assessments/projects/:projectPid (202), save assessmentPid.

Status flow

queued → running → completed
queued → running → failed
draft              (not started via pipeline)

How to poll

1. GET /assessments/:assessmentPid
2. When status is completed or reportAvailable is true → GET /assessments/:assessmentPid/report
3. On failed → GET /assessments/:assessmentPid/stages

curl -sS 'https://api.air.thalus.ai/assessments/<assessmentPid>' \
  -H 'Authorization: Bearer <rawKey>'

List runs: GET /assessments/projects/:projectPid.

End-to-end reminder

Upload → poll documents until connected
       → list artifacts
       → POST assessment
       → poll assessment until completed
       → GET report

See Integration flow for curl commands.

Related

• Uploads — presigned upload flow
• Concepts — Assessment report — report sections
• Errors — retry and rate limits