Tasks and uploads
/v1/tasks/{id}Retrieve a task's status and, once complete, its output.
Sent as the Authorization header. Your key is used only by your browser for this request — it is never sent to Docsbook or stored.
The task ID returned by a generation endpoint
{
"id": "d2e3d1f4-1b3c-4b5c-8d46-1c1d7ee86892",
"status": "SUCCEEDED",
"createdAt": "2024-06-27T19:49:32.335Z",
"output": [
"https://dnznrvs05pmza.cloudfront.net/output.mp4?_jwt=..."
]
}/v1/uploadsStart an ephemeral upload for files up to 200MB.
Sent as the Authorization header. Your key is used only by your browser for this request — it is never sent to Docsbook or stored.
Filename with an extension representative of the contents
Must be ephemeral
{
"uploadUrl": "https://...",
"fields": {},
"runwayUri": "runway://..."
}POST the file to uploadUrl as multipart form data, sending every key in fields as a form field and the contents as file. The runwayUri is then usable anywhere a URL is accepted, for 24 hours. If the upload fails, start over with a new /v1/uploads request rather than retrying — see ephemeral uploads.
Task statuses#
| Status | Meaning |
|---|---|
PENDING |
Accepted and queued |
THROTTLED |
Stored but not enqueued — at your concurrency limit. Treat as PENDING |
RUNNING |
Generating |
SUCCEEDED |
Complete; output is populated |
FAILED |
Failed; read failureCode |
CANCELED |
Cancelled via the cancellation endpoint |
Output URLs expire within 24–48 hours — download and re-host them, as described in Outputs.
Error responses#
| Status | Meaning | Retry? |
|---|---|---|
400 |
Invalid input; error explains |
No |
401 |
Invalid API key | No |
404 |
Resource not found | No |
405 |
Method not supported on this endpoint | No |
429 |
Rate or daily limit reached | Yes |
502 / 503 |
Runway is shedding load | Yes |
504 |
Runway is overloaded | Yes |
Full detail, including backoff strategy, is on the HTTP errors page. Failures after a task is accepted are covered in task failures.
SDK method map#
| Operation | Endpoint | Node.js method |
|---|---|---|
| Generate an image | POST /v1/text_to_image |
client.textToImage.create |
| Generate a video | POST /v1/image_to_video |
client.imageToVideo.create |
| Character performance | POST /v1/character_performance |
client.characterPerformance.create |
| Retrieve a task | GET /v1/tasks/{id} |
client.tasks.retrieve |
| Upload a file | POST /v1/uploads |
client.uploads.createEphemeral |
Node.js — @runwayml/sdk, TypeScript bindings, Node 18+.
Python — runwayml, MyPy-compatible annotations, Python 3.8+.
Both SDKs retry retryable statuses automatically and expose waitForTaskOutput for correct polling.
Related#
- Generation endpoints — creating the tasks you retrieve here
- Making API calls — working code for all of it
- Ephemeral uploads — the SDK path for large files
A $10 credit purchase unlocks every endpoint on this page.