Retrieve a RenderIO command by ID to check status, processing times, output file metadata, errors, and the original request.

Get Command

GET /api/v1/commands/:commandId

Retrieve the current status of a command, including processing times, output file metadata, and the original request. Use this endpoint to poll for results after submitting a command.

Authentication

Requires API key via X-API-KEY header.

Request

Headers

Header	Type	Required	Description
`X-API-KEY`	`string`	Yes	Your API key with `ffsk_` prefix

Path parameters

Parameter	Type	Required	Description
`commandId`	`string`	Yes	The unique identifier returned when the command was submitted.

Response

200 OK

interface CommandPollResponse {
  command_id: string;
  status: "QUEUED" | "PROCESSING" | "SUCCESS" | "FAILED";
  command_type: "FFMPEG_COMMAND" | "CHAINED_COMMAND" | "MULTIPLE_COMMAND" | "YTDLP_COMMAND";
  total_processing_seconds?: number | null;
  ffmpeg_command_run_seconds?: number | null;
  metadata?: Record<string, unknown> | null;
  error_status?: string | null;
  error_message?: string | null;
  output_files?: Record<string, OutputFileMeta>;
  original_request: {
    input_files: Record<string, string>;
    output_files: Record<string, string>;
    ffmpeg_command?: string;
    ffmpeg_commands?: string[];
  };
}

interface OutputFileMeta {
  file_id: string;
  storage_url: string | null;
  storage_location?: "INTERNAL" | "EXTERNAL";
  external_uri?: string | null;
  external_object_key?: string | null;
  status: "PROCESSING" | "STORED" | "FAILED";
  rendi_store_type: "OUTPUT" | "STORED_FILE" | "UPLOAD";
  is_deleted: boolean;
  filename: string;
  size_mbytes: number | null;
  duration?: number | null;
  file_type?: string | null;
  file_format?: string | null;
  codec?: string | null;
  pixel_format?: string | null;
  mime_type?: string | null;
  width?: number | null;
  height?: number | null;
  frame_rate?: number | null;
  bitrate_video_kb?: number | null;
  bitrate_audio_kb?: number | null;
}

Field	Type	Description
`command_id`	`string`	Unique identifier for the command.
`status`	`string`	Current status: `QUEUED`, `PROCESSING`, `SUCCESS`, or `FAILED`.
`command_type`	`string`	Type of command: `FFMPEG_COMMAND`, `CHAINED_COMMAND`, `MULTIPLE_COMMAND`, or `YTDLP_COMMAND`.
`total_processing_seconds`	`number \| null`	Total wall-clock time from submission to completion, in seconds.
`ffmpeg_command_run_seconds`	`number \| null`	Time spent running FFmpeg only, in seconds.
`metadata`	`Record<string, unknown> \| null`	The metadata object you attached when submitting the command.
`error_status`	`string \| null`	Machine-readable error code if `status` is `FAILED`.
`error_message`	`string \| null`	Human-readable error description if `status` is `FAILED`.
`output_files`	`Record<string, OutputFileMeta>`	Map of output aliases to file metadata. Present when `status` is `SUCCESS`.
`original_request`	`object`	The original input/output mappings and FFmpeg command(s) you submitted.

OutputFileMeta fields

Field	Type	Description
`file_id`	`string`	Unique identifier for the output file.
`storage_url`	`string \| null`	RenderIO download URL for managed storage, or the configured public/CDN URL for external storage. `null` for a private BYOB output.
`storage_location`	`"INTERNAL" \| "EXTERNAL"`	Whether the bytes live in RenderIO-managed storage or a customer-owned bucket.
`external_uri`	`string \| null`	Persistent `s3://bucket/key` locator for an external output.
`external_object_key`	`string \| null`	Persistent object key in the customer's bucket.
`status`	`string`	File status: `PROCESSING`, `STORED`, or `FAILED`.
`rendi_store_type`	`string`	How the file was created: `OUTPUT`, `STORED_FILE`, or `UPLOAD`.
`is_deleted`	`boolean`	Whether the file has been deleted from storage.
`filename`	`string`	Original filename.
`size_mbytes`	`number \| null`	File size in megabytes.
`duration`	`number \| null`	Duration in seconds (for audio/video files).
`file_type`	`string \| null`	General type (e.g., `video`, `audio`, `image`).
`file_format`	`string \| null`	Container format (e.g., `mp4`, `webm`, `png`).
`codec`	`string \| null`	Primary codec (e.g., `h264`, `vp9`, `aac`).
`pixel_format`	`string \| null`	Pixel format (e.g., `yuv420p`).
`mime_type`	`string \| null`	MIME type (e.g., `video/mp4`).
`width`	`number \| null`	Width in pixels (for video/image).
`height`	`number \| null`	Height in pixels (for video/image).
`frame_rate`	`number \| null`	Frame rate in fps (for video).
`bitrate_video_kb`	`number \| null`	Video bitrate in kb/s.
`bitrate_audio_kb`	`number \| null`	Audio bitrate in kb/s.

Managed and external outputs

For a RenderIO-managed output, storage_location is INTERNAL and storage_url is the download URL.

For a BYOB output, storage_location is EXTERNAL. A private bucket has storage_url: null, but external_uri and external_object_key still identify the object. These values remain in the command result and can be retrieved later without rerunning the command.

{
  "storage_location": "EXTERNAL",
  "external_uri": "s3://your-company-media/renderio/COMMAND_ID/output.mp4",
  "external_object_key": "renderio/COMMAND_ID/output.mp4",
  "storage_url": null
}

If the storage destination had a working public_base_url when the command completed, storage_url contains that public URL instead. See Bring Your Own Bucket for private-download and public-URL examples.

Error responses

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid API key.
`404`	`NOT_FOUND`	No command found with the given ID, or the command belongs to a different account.
`429`	`RATE_LIMITED`	Too many requests. Retry after the period indicated in the `Retry-After` header.

Examples

curl

curl https://renderio.dev/api/v1/commands/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-KEY: ffsk_your_api_key_here"

JavaScript (fetch)

const commandId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";

const response = await fetch(
  `https://renderio.dev/api/v1/commands/${commandId}`,
  {
    headers: {
      "X-API-KEY": "ffsk_your_api_key_here",
    },
  },
);

const command = await response.json();
console.log("Status:", command.status);

if (command.status === "SUCCESS") {
  for (const [alias, file] of Object.entries(command.output_files)) {
    const location = file.storage_url ?? file.external_uri ?? file.external_object_key;
    console.log(`${alias}: ${location}`);
  }
}

Python (requests)

import requests

command_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

response = requests.get(
    f"https://renderio.dev/api/v1/commands/{command_id}",
    headers={
        "X-API-KEY": "ffsk_your_api_key_here",
    },
)

command = response.json()
print("Status:", command["status"])

if command["status"] == "SUCCESS":
    for alias, file in command["output_files"].items():
        location = (
            file.get("storage_url")
            or file.get("external_uri")
            or file.get("external_object_key")
        )
        print(f"{alias}: {location}")

Get Command API Reference