Skip to main content

​
Async jobs and polling

Most write operations are asynchronous.

​
What returns immediately

These endpoints accept work and return IDs you can poll:
  • POST /projects
  • POST /projects/{projectId}/tasks/stem-separation
  • POST /projects/{projectId}/tasks/lyrics-sync
  • POST /projects/{projectId}/exports

​
What to poll

  • Poll GET /tasks/{taskId} for execution status and hydrated task output.
  • Read GET /projects/{projectId} for long-lived project state.
  • Read GET /exports/{exportId} for fresh export download URLs.

​
Practical polling model

  1. Start a mutation and store the returned IDs.
  2. Poll GET /tasks/{taskId} until the task reaches a terminal state.
  3. Re-read the durable resource by ID instead of trusting stale cached state.
  4. For downloads, fetch GET /exports/{exportId} when you are ready to use the URL.

​
Why this matters

  • Task status is the execution timeline.
  • Project state is the durable source of truth.
  • Export download URLs should be treated as refreshable rather than permanent.