Project Status API

Use GET https://api.sogni.ai/v2/projects/:id to check a generation project while it is pending, queued, processing, completed, failed, or canceled. This is a read-only lookup; submit and cancel projects through your existing SDK integration.

#Migrating from v1

Change your status-polling URL from /v1/projects/:id to /v2/projects/:id and authenticate as the account that submitted the project. The v1 endpoint keeps its existing terminal-result behavior for compatibility: a v1 404 does not establish that a project was never submitted or is still running.

On v2, HTTP 200 means the project is known, not that generation succeeded or finished. Read data.project.status and data.project.finished. The v2 terminal names are failed and canceled, rather than v1's legacy errored and cancelled names. Do not change an SDK's internal recovery URL without also adapting its terminal-state handling.

This endpoint accepts a generation project ID, not a chat-run, workflow-run, or individual worker-job ID.

#Authentication and request

Use an API key from the Sogni dashboard belonging to the submitting account. Session access tokens also work. Keep API keys on your server; do not embed them in a public browser bundle.

Set SOGNI_API_KEY in your server environment and replace PROJECT_ID:

curl --fail-with-body 'https://api.sogni.ai/v2/projects/PROJECT_ID' \
  -H "Authorization: Bearer $SOGNI_API_KEY"

The legacy api-key header is also accepted. The optional appSource query parameter (alias app_source) restricts the lookup to the exact application attribution used when submitting the project. Omit it if you do not need this additional filter. It does not grant access to another account's projects.

#Response

This abbreviated example shows a queued project; additional metadata may be present:

{
  "status": "success",
  "data": {
    "project": {
      "id": "PROJECT_ID",
      "status": "queued",
      "finished": false,
      "workerJobs": [],
      "completedWorkerJobs": []
    }
  }
}

data.project.status	Meaning	finished
pending	Accepted and awaiting authorization	false
queued	Waiting to start work	false
processing	Assigned or rendering	false
completed	At least one output completed successfully	true
failed	Terminal failure without a successful output	true
canceled	Terminal cancellation without a successful output	true

A partially successful project retains the existing project-level completed meaning. Inspect job results and jobCountCompletedByState, when available, to distinguish individual successes, failures, and cancellations. The job arrays are bounded summaries (up to 16 entries each), not a complete job listing for large batches. Accepting a cancellation request does not mean worker cleanup has finished; continue polling until finished is true.

Zero-output failures and cancellations return a compact response with statusOnly: true, empty job arrays, endTime, and expiresAt. Both timestamps are Unix milliseconds, and expiresAt is 24 hours after endTime. These responses may include model identity and a reason, but do not contain prompts, reference inputs, recipes, or downloadable results. Do not assume those omitted fields exist.

#Polling and HTTP errors

Poll with a delay, for example every two seconds, and stop when finished is true. Apply an overall deadline appropriate to your application. Responses use Cache-Control: no-store; normal API rate limits still apply.

HTTP status	How to handle it
200	Inspect data.project.status and finished; a known failure or cancellation also returns 200.
401	Supply valid credentials for the submitting account.
404	No current record is available for this owner and optional application filter. Check the ID, account, and retention window.
429	Slow down and honor Retry-After when provided.
503	Status is temporarily unverifiable. Retry with exponential backoff and jitter; do not treat it as project loss or resubmit solely because of this response.

Another account's project returns 404, not its status. A locally generated ID is not yet known until submission reaches the service. A 404 is not proof that a historical project never existed.

#Retention and compatibility

Compact failed/canceled status is available for at most 24 hours after termination. Polling does not extend expiry. This is temporary status information, not a permanent history API or a guaranteed minimum under service data loss or cache eviction. Save terminal outcomes in your own system if you need a longer audit trail. Result-artifact retention is unchanged.

The change cannot reconstruct older failed/canceled projects that were never recorded. Existing successful and partially successful result lookups retain their existing behavior. There is no need to update an SDK merely to call this REST endpoint from your own HTTP client.

For SDK users, JavaScript SDK 5.29.1 and Python SDK 5.29.1 also include matching completion-wait fixes for cancellation and recovered failure handling. See the SDK guides and the general API reference.