> ## Documentation Index
> Fetch the complete documentation index at: https://docs.percify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a generation: GET /v1/generations/{id}

> GET /v1/generations/{id} returns a Percify generation's status, output URLs and credits. Add ?wait=45 to wait on the server until it finishes.

`GET https://api.percify.io/v3/playground/v1/generations/{id}` returns the current state of a generation you started with [`POST /v1/run`](https://docs.percify.io/api-reference/generations/run). When `status` is `succeeded`, the files are in `output.urls`. Add `?wait=45` and Percify holds the request open until the run finishes or 45 seconds pass, so you need fewer calls.

```http theme={"system"}
GET https://api.percify.io/v3/playground/v1/generations/{id}?wait=45
Authorization: Bearer pk_live_…
```

## Parameters

**id** `string` *required*

The generation id (a UUID) from `POST /v1/run`. You can only read generations from your own account.

**wait** `integer`

Seconds to wait on the server for the run to finish, from 5 to 55. Values outside that range are clamped. Leave it out to get the current state immediately.

## Response

**data.id** `string`

The generation id.

**data.modelId** `string`

The model that ran.

**data.status** `string`

`processing`, `succeeded` or `failed`. See [statuses](https://docs.percify.io/api-reference/async-jobs.md#generation-statuses).

**data.output** `object | null`

Set when `status` is `succeeded`: `type` is `image`, `video` or `audio`, and `urls` is an array of file URLs on `cdn.percify.io`.

**data.error** `string | null`

Why the run failed, when `status` is `failed`.

**data.creditsSpent** `integer`

Credits charged when the run started. On a failed run the same amount was refunded to your balance.

**data.createdAt** `string`

When the run started.

**data.mediaDurationSec** `number | null`

Length in seconds of the input audio or video that a duration-billed model was priced on, such as lip-sync. `null` for other models.

**data.stillRunning** `boolean`

Only present with `wait`: `true` when the wait ended before the run did. Call again.

`input` and `completedAt` also appear in the object and are `null` on this endpoint.

## Example: wait for the result

```bash cURL theme={"system"}
curl -s "https://api.percify.io/v3/playground/v1/generations/3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83?wait=45" \
  -H "Authorization: Bearer $PERCIFY_API_TOKEN"
```

```javascript Node.js theme={"system"}
const API = "https://api.percify.io/v3/playground/v1";
const headers = { Authorization: `Bearer ${process.env.PERCIFY_API_TOKEN}` };

async function waitForGeneration(id) {
  for (;;) {
    const res = await fetch(`${API}/generations/${id}?wait=45`, { headers });
    const { data } = await res.json();
    if (data.status === "succeeded") return data.output.urls;
    if (data.status === "failed") throw new Error(data.error);
  }
}

console.log(await waitForGeneration("3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83"));
```

```python Python theme={"system"}
import os, requests

API = "https://api.percify.io/v3/playground/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PERCIFY_API_TOKEN']}"}

def wait_for_generation(gen_id):
    while True:
        data = requests.get(f"{API}/generations/{gen_id}", params={"wait": 45},
                            headers=HEADERS, timeout=70).json()["data"]
        if data["status"] == "succeeded":
            return data["output"]["urls"]
        if data["status"] == "failed":
            raise RuntimeError(data["error"])

print(wait_for_generation("3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83"))
```

```json Succeeded theme={"system"}
{
  "success": true,
  "data": {
    "id": "3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83",
    "modelId": "gpt-image-2",
    "status": "succeeded",
    "input": null,
    "output": {
      "type": "image",
      "urls": ["https://cdn.percify.io/media-assets/playground/3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83-0"]
    },
    "error": null,
    "creditsSpent": 4,
    "createdAt": "2026-09-16T09:41:07.512Z",
    "completedAt": null,
    "mediaDurationSec": null
  }
}
```

```json Still running after the wait theme={"system"}
{
  "success": true,
  "data": {
    "id": "3f6c2a9e-8b1d-4c57-9a0e-2d4b7f1c6e83",
    "modelId": "gpt-image-2",
    "status": "processing",
    "input": null,
    "output": null,
    "error": null,
    "creditsSpent": 4,
    "createdAt": "2026-09-16T09:41:07.512Z",
    "completedAt": null,
    "mediaDurationSec": null,
    "stillRunning": true
  }
}
```

## Errors

| Status | Message starts with | Cause |
| - | - | - |
| `400` | `Invalid generation id` | The id is not a UUID. Use the `id` from `POST /v1/run`. |
| `401` | `Invalid, expired, or revoked API key` | See [Authentication](https://docs.percify.io/percify/api-auth.md). |
| `404` | `Generation not found` | No generation with this id exists in the account that owns the key. |
| `429` | `API key rate limit exceeded` | More than 60 requests a minute on this key. |

## Tips

* Save the files you need. `output.urls` point to `cdn.percify.io`, and your own storage is the copy you control.
* Set your HTTP client timeout above the `wait` value, for example 70 seconds for `wait=45`.
* Every poll counts toward the 60 requests a minute per key. `wait=45` keeps a single job to about one request a minute.
* For long lip-sync videos, a [webhook](https://docs.percify.io/guides/webhooks.md) saves you from polling at all.

## Related

> [card] [Async jobs and polling](https://docs.percify.io/api-reference/async-jobs.md)
>
> Statuses, time limits and refunds.

> [card] [Start a generation](https://docs.percify.io/api-reference/generations/run.md)
>
> The call that returns the id.

> [card] [Webhooks](https://docs.percify.io/guides/webhooks.md)
>
> Get the finished result pushed to you.

> [card] [Errors and rate limits](https://docs.percify.io/api-reference/errors-and-limits.md)
>
> Every status code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.