Probe Media Metadata

Use mode: "probe" to run ffprobe against an input URL. When the job completes, enriched metadata is returned on the job record under probe — no output file is written and no storage upload occurs.

The response preserves the raw ffprobe shape (format, streams, chapters, programs) and adds convenience flags such as hasVideo, hasAudio, isVideo, isAudio, isImage, isHdr, stream counts, codec names, dimensions, duration, size, bitrate, and frame rate.

Use this when you need media metadata before deciding which encode recipe to run, or to power upload validation and CMS previews.

Basic usage

cURL

curl -X POST https://api.xora.sh/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "probe",
    "input": {
      "url": "https://example.com/video.mp4"
    }
  }'

Node.js

const create = await fetch('https://api.xora.sh/v1/jobs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    mode: 'probe',
    input: { url: 'https://example.com/video.mp4' },
  }),
});

const { id } = await create.json();

const status = await fetch(`https://api.xora.sh/v1/jobs/${id}`, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
const job = await status.json();
console.log(job.probe);

Poll GET /v1/jobs/:id (or use a webhook) until state is completed. Read metadata from probe, not output or output_files.

Request shape

Field	Type	Required	Description
mode	string	Yes	Must be "probe"
input.url	string	One of	HTTPS or S3 URL of the media file to inspect
input.uploadId	string	One of	Id from POST /v1/uploads, for locally uploaded files. Provide exactly one of url or uploadId.
stageInput	boolean	No	Skip input staging when your origin supports byte ranges. Defaults to true. See Input staging.
webhookUrl	string	No	Optional webhook for completion notification

Probe jobs do not accept output, recipe, outputPath, or preset bodies.

Response shape

When the job completes, probe includes:

• Raw ffprobe fields under format, streams, chapters, and programs
• Top-level convenience flags such as hasVideo, hasAudio, isHdr, durationSeconds, width, height, videoCodec, and audioCodec
• A nested flags object with the same convenience fields for programmatic access

Example (truncated):

{
  "id": "01KSD388ERH85FGR79JCW0SZZ0",
  "state": "completed",
  "mode": "probe",
  "probe": {
    "hasVideo": true,
    "hasAudio": true,
    "isVideo": true,
    "durationSeconds": 125.4,
    "width": 1920,
    "height": 1080,
    "videoCodec": "h264",
    "audioCodec": "aac",
    "flags": {
      "hasVideo": true,
      "hasAudio": true,
      "isVideo": true
    },
    "format": { "duration": "125.400000", "bit_rate": "4500000" },
    "streams": []
  }
}

Note

Probe jobs do not transcode or remux media. They only inspect the input and return metadata on the job record. For web delivery decisions based on probe results, follow up with webReady or compress.

Related

• Input staging — set stageInput: false when your origin supports byte ranges
• Web Ready Video — uses internal probing to pick passthrough vs encode
• Output formats — media formats for transcode recipes