DocsAPI referenceOperations

Read media metadata

The container, duration and streams of input, read with ffprobe: nothing is encoded. Waits up to 25 seconds for the job to end, or not at all with ?wait=false. A job that has ended answers 200, with the document in probe when it succeeded; a job still queued or running answers 202 and probe is null. The document is also the job's output file. Creates the same Job as POST /v1/jobs, with operation set.

POST /v1/probe

Needs an API key: Authorization: Bearer $VIDEXO_API_KEY.

Parameters

Parameters
Name	In	Type	Description
`wait`	query	one of `true`, `false`	Wait up to 25 seconds for the job to end (`true`, the default), or answer at once (`false`).
`idempotency-key`	header	string, up to 255 characters	Makes retries safe for 24 hours. Up to 255 printable ASCII characters. One key space per account across every endpoint that creates a job.

Body ProbeRequest

Body fields
Name	Type	Description
`input` required	string or object	An http or https URL, `videxo://uploads/<upload_id>`, `{ "url" }` or `{ "upload_id" }`.
`filename`	string, up to 105 characters	The stored file name, `<name>.<format>` by default; one extension, matching `format`.
`webhook_url`	string, URL, up to 2,048 characters or null	An https URL that gets the job when it ends (M4).
`metadata`	map of string to string, up to 500 characters	Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500.

Request

bash

curl "$VIDEXO_API_URL/v1/probe" \
  -H "Authorization: Bearer $VIDEXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "https://videxo.io/samples/talk.mp4"
}'

JavaScript

const response = await fetch(`${process.env.VIDEXO_API_URL}/v1/probe`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDEXO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "input": "https://videxo.io/samples/talk.mp4"
  }),
});
const job = await response.json();

Response

200 JSON

{
  "id": "job_3k9x0c2mfq8w1n7r5t4b6v2z",
  "state": "succeeded",
  "kind": "operations",
  "operation": "probe",
  "spec": {
    "inputs": {
      "source": {
        "url": "https://videxo.io/samples/talk.mp4"
      }
    },
    "outputs": [
      {
        "name": "metadata",
        "type": "metadata",
        "input": "source",
        "filename": "metadata.json",
        "format": "json"
      }
    ]
  },
  "command": null,
  "input_files": null,
  "output_files": null,
  "ffmpeg_command": null,
  "steps": [
    {
      "tool": "ffprobe",
      "inputs": [
        "source"
      ],
      "outputs": [
        "metadata"
      ],
      "command": null
    }
  ],
  "webhook_url": null,
  "metadata": {},
  "progress": null,
  "error": null,
  "outputs": [
    {
      "alias": "out_metadata",
      "name": "metadata",
      "filename": "metadata.json",
      "size_bytes": 612,
      "sha256": "9f2c4e1a7b3d5f60c8e2a4b6d8f0e1c3a5b7d9f1e3c5a7b9d1f3e5c7a9b1d3f5",
      "content_type": "application/json",
      "expires_at": "2026-11-05T12:01:09.000Z",
      "download_url": "https://api.videxo.io/v1/files/job_3k9x0c2mfq8w1n7r5t4b6v2z/out_video?account=acc_example&expires=1793797269&signature=example",
      "download_url_expires_at": "2026-11-04T13:01:09.000Z",
      "deleted_at": null
    }
  ],
  "usage": {
    "seconds": 1,
    "input_bytes": 48000000,
    "output_bytes": 612,
    "credits": 1,
    "bill": {
      "lines": [
        {
          "kind": "metadata",
          "credits": 0
        }
      ],
      "data": {
        "input_bytes": 48000000,
        "output_bytes": 612,
        "credits": 0.48
      },
      "processing": {
        "seconds": 1,
        "included_seconds": 0,
        "credits": 0.167
      }
    }
  },
  "created_at": "2026-11-04T12:00:00.000Z",
  "started_at": "2026-11-04T12:00:01.000Z",
  "finished_at": "2026-11-04T12:00:04.000Z",
  "probe": {
    "container": "mov,mp4,m4a,3gp,3g2,mj2",
    "duration": 62.4,
    "start_time": 0,
    "size_bytes": 48000000,
    "bit_rate": 6153846,
    "tags": {
      "major_brand": "isom",
      "creation_time": "2026-10-30T09:12:00.000000Z"
    },
    "streams": [
      {
        "index": 0,
        "type": "video",
        "codec": "h264",
        "profile": "High",
        "duration": 62.4,
        "bit_rate": 6000000,
        "width": 1920,
        "height": 1080,
        "rotation": 0,
        "fps": 29.97,
        "pixel_format": "yuv420p",
        "frames": 1870,
        "cover_art": false,
        "tags": {
          "language": "eng"
        }
      },
      {
        "index": 1,
        "type": "audio",
        "codec": "aac",
        "profile": "LC",
        "duration": 62.38,
        "bit_rate": 128000,
        "channels": 2,
        "channel_layout": "stereo",
        "sample_rate": 48000,
        "tags": {
          "language": "eng"
        }
      }
    ]
  }
}

Responses

Responses
Status	Body	When
200	ProbeResponse	The job ended within the wait, or this Idempotency-Key made it earlier (same endpoint and body).
202	ProbeResponse	The job, still queued or running; `probe` is null.
400	Problem	invalid_request (with `errors`) or command_invalid (with `problems`)
401	Problem	authentication_failed (missing_api_key, invalid_api_key, api_key_revoked, api_key_expired)
402	Problem	usage_cap_reached or out_of_credits
403	Problem	permission_denied (account_disabled, token_scope)
404	Problem	not_found (upload)
409	Problem	conflict (idempotency_key_reused)
413	Problem	limit_exceeded (request_body_size): the body is larger than 512 KB
415	Problem	invalid_request (not_json): the body is not sent as application/json
429	Problem	rate_limited, with Retry-After in seconds
500	Problem	internal_error
503	Problem	service_unavailable (temporary): the account's free credits are still being granted, or a part of the service did not answer