# Async Jobs

> Track the status of asynchronous operations such as video generation via the jobs endpoints.

- Canonical: https://tchavi.com/en/docs/jobs

---


Some endpoints — currently video generation — run asynchronously. They respond immediately with a job `id` and you track completion via these endpoints.

## Retrieve a job

<Endpoint method="GET" path="/v1/jobs/:id" />

Returns the full job record. The payload shape depends on `status`:

- `pending` / `processing` — no `output` yet; `tchavi.credits_used` is set.
- `completed` — `output.video_url`, `output.duration`, `output.resolution`, `output.file_size_mb`, `output.url_expires_at`.
- `failed` — `error.message`, `error.code`, and `tchavi.credits_refunded` (the charged credits are returned automatically).

## List jobs

<Endpoint method="GET" path="/v1/jobs" />

Lists the caller's jobs, most recent first. Query params: `status` (filter), `limit` (1–50, default 20), `offset` (default 0).

## Example

<CodeTabs>

```tchavi
import Tchavi from '@tchavi/sdk';
const client = new Tchavi({ apiKey: 'YOUR_API_KEY' });

// Retrieve a specific job
const job = await client.jobs.retrieve('job_abc123');
console.log(job.status, job.output?.video_url);

// List the 10 most recent completed jobs
const { data } = await client.jobs.list({ status: 'completed', limit: 10 });
for (const j of data) {
  console.log(j.created_at, j.model, j.output?.video_url);
}
```

```curl
# Retrieve
curl https://tchavi.com/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

# List (most recent 10 completed)
curl "https://tchavi.com/api/v1/jobs?status=completed&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

</CodeTabs>

See [Video Generation](/en/docs/video-generation) for the endpoint that produces these jobs.