Source: https://docs.sogni.ai/api-reference/project-status/

# 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.

## [#](https://docs.sogni.ai/api-reference/project-status/#migrating-from-v1)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.

## [#](https://docs.sogni.ai/api-reference/project-status/#authentication-and-request)Authentication and request

Use an API key from the [Sogni dashboard](https://dashboard.sogni.ai/api-key) 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.

## [#](https://docs.sogni.ai/api-reference/project-status/#response)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 image, video, and audio 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.

## [#](https://docs.sogni.ai/api-reference/project-status/#polling-and-http-errors)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`; this read shares a per-client rate limit with other public API reads.

| HTTP status | How to handle it |
| --- | --- |
| `200` | Inspect `data.project.status` and `finished`; a known failure or cancellation also returns `200`. |
| `400` | The ID is malformed (longer than 128 characters, `.`, or `..`). |
| `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.

## [#](https://docs.sogni.ai/api-reference/project-status/#retention-and-compatibility)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](https://docs.sogni.ai/sogni-sdk/) and the [general API reference](https://docs.sogni.ai/api-reference/).