---
title: Request status
description: GET /v1/requests/{request_id}/status — a lightweight check of a generation's status and progress by request_id. No extra key permission is needed.
icon: Activity
---

Check the status of a submitted generation by its `request_id`. The call is lightweight and suits frequent polling when you don't use a webhook.

## Playground

<Callout type="info" title="Use a test key here">
Paste a `clipia_test_…` key into the form below: it charges no credits and calls no models, and the response has the same shape. The form keeps the key in this browser, so never enter a live `clipia_live_…` key here: it is a server-side secret. See [Sandbox](/en/docs/getting-started/sandbox).
</Callout>

<ApiPlayground path="/v1/requests/{request_id}/status" method="get" />

`GET /v1/requests/:id/status` returns the current status of the generation and, when known, its progress. Any valid key on the same account works — no extra permission is needed.

<Method name="GET" path="/v1/requests/:id/status" />

## Request

<TypeTable
  type={{
    id: { type: 'string', description: 'The request_id from the submit response: a UUID, or an ID with the cmp_ or prs_ prefix for video compositions and presentations created through MCP.', required: true }
  }}
/>

<Tabs items={['cURL', 'TypeScript', 'Python']}>
<Tab value="cURL">

```bash
curl https://api.clipia.ai/v1/requests/764cabcf-b745-4b3e-ae38-1200304cf45b/status \
  -H "Authorization: Bearer $CLIPIA_KEY"
```

</Tab>
<Tab value="TypeScript">

```ts
const status = await clipia.queue.status('764cabcf-b745-4b3e-ae38-1200304cf45b');
console.log(status.status, status.progress);
```

</Tab>
<Tab value="Python">

```python
status = client.status("764cabcf-b745-4b3e-ae38-1200304cf45b")
print(status.status, status.progress)
```

</Tab>
</Tabs>

**Response `200`**

```json
{
  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
  "status": "IN_PROGRESS",
  "queue_position": 0,
  "progress": 45
}
```

<TypeTable
  type={{
    request_id: { type: 'string', description: 'Request identifier' },
    status: { type: 'string', description: 'IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED or CANCELED' },
    queue_position: { type: 'integer', description: 'Deprecated: always 0, the queue position is not computed. Kept for compatibility; rely on status and progress' },
    progress: { type: 'integer', description: 'Progress from 0 to 100. Omitted when unknown: not every model reports it' },
    warnings: { type: 'array', description: '[{ code, parameter, message }] — parameters the server dropped while running the request, e.g. audio_dropped: the video is generated without sound. Omitted when there is nothing to report. See "Generation result" for details' }
  }}
/>

## Errors

| HTTP | `code` | `message` | When |
|------|--------|-----------|------|
| 400 | `invalid_request` | `invalid_request_id` | the ID doesn't look like a `request_id` |
| 404 | `not_found` | `request_not_found` | the request doesn't exist or belongs to another account |

<Callout type="info" title="Which call to use">
`/status` is meant for frequent polling. Fetch media links with [`GET /v1/requests/:id`](/en/docs/api-reference/result). If you passed a `webhook_url` on submit, you don't need to poll at all — see [Webhooks](/en/docs/api-reference/webhooks). Poll no more than once per second: these calls count toward your [rate limit](/en/docs/api-reference/rate-limits).
</Callout>