Reference · Probe

# POST/ffprobe/analyze

Runs ffprobe on one file and returns what it reports as JSON. Name the sections you want in `probe`, each with the fields to return. A probe is charged like any other request that succeeds: on the file’s size, the result’s size and the seconds ffprobe ran.

## Request body

Request body

- `file_path` (string): Required. dir_id/file_name of an uploaded file, or a public HTTPS URL. A URL is copied in, probed and deleted when the request ends.
- `probe` (object): What to report. Left out, the format and every stream, with all their fields.
- `probe.format[]` (string[]): Fields of the container to return. An empty array means every field. Field names are letters, digits and underscores.
- `probe.streams[]` (string[]): Fields of each stream.
- `probe.chapters[]` (string[]): Fields of each chapter.
- `probe.programs[]` (string[]): Fields of each program.
- `probe.frames[]` (string[]): Fields of each frame. Needs select_streams, and reads at most 30 seconds or 3000 frames.
- `probe.packets[]` (string[]): Fields of each packet. The same conditions as frames.
- `probe.error[]` (string[]): Fields of the error ffprobe reports, if it reports one.
- `probe.select_streams` (string): A stream specifier, such as v:0 or a. Required with frames or packets.
- `probe.read_intervals` (string): Which parts to read, in ffprobe’s notation, such as 10%+5. With frames or packets, no interval may be longer than 30 seconds or 3000 frames; left out, the first 30 seconds are read.
- `probe.count_frames` (boolean): Count the frames of each stream by decoding it.
- `probe.skip_frame` (string): Frames the decoder may skip: none, default, noref, bidir, nokey, nointra or all.
- `probe.analyzeduration` (number | string): How much of the file to analyze, in seconds (10) or with a unit (“10s”, “500ms”). At most 60 seconds.
- `probe.probesize` (number | string): How many bytes to probe, as a number or with a unit (“10M”). At most 50 MB.

## Example

Request

```bash
curl https://media.logicboostkit.com/ffprobe/analyze \
  -H "Authorization: Basic $MEDIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "dir_pi23jgy1yxlmigi873bz/source.mp4",
    "probe": {
      "format": ["duration", "size", "bit_rate"],
      "streams": ["codec_name", "width", "height"]
    }
  }'
```

Response

```http
HTTP/1.1 200 OK
X-Request-Id: job_0mv6iygbcl43togsnvc4g2wc

{
  "ok": true,
  "result": {
    "streams": [
      {
        "codec_name": "h264",
        "width": 1920,
        "height": 1080
      },
      {
        "codec_name": "aac"
      }
    ],
    "format": {
      "duration": "634.533333",
      "size": "1937244979",
      "bit_rate": "24424185"
    }
  },
  "usage": {
    "time_sec": 0.31,
    "input_size_gb": 1.804199982,
    "output_size_gb": 1.49e-7,
    "gb_sec": 0.55930204
  },
  "request_id": "job_0mv6iygbcl43togsnvc4g2wc",
  "amount_usd": 0.007449903
}
```

## Response fields

Response fields

- `ok` (boolean): true when ffprobe finished.
- `result` (object): ffprobe’s JSON: one member per section you asked for. As ffprobe does, it reports most numbers as strings.
- `usage.time_sec` (number): The seconds ffprobe ran, measured on the reference machine.
- `usage.input_size_gb` (number): The file’s size.
- `usage.output_size_gb` (number): The size of result.
- `usage.gb_sec` (number): What the request is charged on.
- `request_id` (string): The request’s id, also sent as the X-Request-Id header.
- `amount_usd` (number): What the request was charged, in USD.

## Status codes

Status codes

- **200**: ffprobe finished. Charged.
- **400**: The body is malformed, file_path isn’t dir_id/file_name or a public HTTPS URL, the file is a playlist or manifest, a field name or a control is invalid, frames or packets were asked for without select_streams, or a limit above is exceeded.
- **401**: The `Authorization` header is missing, or the key is invalid, revoked or expired.
- **403**: The account isn’t active, or the file is over 5 GB. The error says what to do.
- **404**: `Directory not found` or `File not found in directory`.
- **429**: More than 300 requests in a minute on this key, or 50 of the account’s jobs already in progress. Wait for the number of seconds in `Retry-After`.
- **500**: ffprobe failed, ran out of time, or the result was too large to return. Ask for fewer fields or a shorter interval. Not charged.
- **503**: Too busy to start the probe now. Retry after the seconds in Retry-After.

Every error has the shape `{"ok": false, "error": "…"}` and is never charged.

## Guides

Guides that use this endpoint

- **[Read video metadata with ffprobe](https://media.logicboostkit.com/docs/video-metadata)**: Duration, codecs, resolution and frame rate, as JSON.