> For the complete documentation index, see [llms.txt](https://monkey-gun.gitbook.io/monkeygun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://monkey-gun.gitbook.io/monkeygun/guides/async-jobs.md).

# Async jobs

Creations with AI clips or full AI video can take minutes. Ask for a job id and poll it.

Add `"async": true` to any `from-data` call.

```bash
curl -X POST https://api.monkeygun.com/v1/videos/from-data -H "Authorization: Bearer $MK_KEY" \
  -d '{ "async": true, "title": "…", "brief": "…", "data": { … }, "clips": { "provider": "kling", "count": 1, "seconds": 5 } }'
```

```json
HTTP 202
{ "ok": true, "jobId": "job-mug7lnzkvw449l", "status": "creating", "poll": "/v1/jobs/job-mug7lnzkvw449l",
  "note": "Creating. Poll the job (videoId appears when the script/voice/images are done), or listen for video.created then video.rendered on your webhook." }
```

The same route runs in the background with the same body. Internal limits still apply (the director call is capped at 150 seconds), so `async` protects you from your own edge timeouts, not from a brief that is too long for the model.

## Poll

```bash
curl https://api.monkeygun.com/v1/jobs/job-mug7lnzkvw449l -H "Authorization: Bearer $MK_KEY"
```

```json
{
  "id": "job-mug7lnzkvw449l",
  "status": "rendering",
  "createdAt": "…", "updatedAt": "…",
  "videoId": "vid-391",
  "videoStatus": "rendering",
  "media": { "public": true, "mediaKey": "cb66…", "url": "https://…/vid-391.mp4?k=cb66…", "renderUrl": null, "thumbnail": null, "watchUrl": "https://monkeygun.com/w/vid-391?k=cb66…" },
  "result": { "videoId": "vid-391", "status": "rendering", "charged": 160, "external_id": "…", "…": "…" },
  "error": null
}
```

| Job status  | Meaning                                                             |
| ----------- | ------------------------------------------------------------------- |
| `creating`  | Script, voice and visuals in progress. No `videoId` yet             |
| `rendering` | Video exists; the file is being made. `videoId` and `media` are set |
| `done`      | `videoStatus` is `rendered`; `media.renderUrl` plays                |
| `failed`    | `error` says why. Anything charged for a failed step is refunded    |

Poll every 5 to 10 seconds. `video.created` fires with `jobId` when creation finishes; `video.rendered` when the file exists. Jobs are per account; another account's job id is a 404.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://monkey-gun.gitbook.io/monkeygun/guides/async-jobs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.