Jobs

POST /v1/jobs

Queue a video for analysis. Returns 202 Accepted with the job.

Request body

Send exactly one of url or upload_key.

custom_query needs at least one question and objects at least one thing: without them the job is refused with INVALID_CAPABILITIES (422). Every limit is on Limits.

curl -X POST https://api.netraflow.com/v1/jobs \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_live_your_key_here" \
  -H "Idempotency-Key: my-unique-key-123" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "capabilities": ["transcription", "summary", "brands"],
    "brands": ["Nike"]
  }'

{
  "data": {
    "job_id": "job_abcdefghij123456",
    "status": "pending",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "platform": "youtube",
    "capabilities": ["transcription", "summary", "brands"],
    "brands": ["Nike"],
    "language": null,
    "video_title": null,
    "video_duration_seconds": null,
    "video_thumbnail_url": null,
    "credits_estimated": 66,
    "credits_charged": null,
    "processing_seconds": null,
    "return_proof": true,
    "follow_id": null,
    "created_at": "2026-04-03T12:00:00.000Z",
    "started_at": null,
    "completed_at": null
  },
  "meta": { "request_id": "req_xyz789" }
}

The job echoes back the queries, brands, surfaces, objects and from_job you sent. A job that starts at once can already be processing in the 202.

Idempotency

Send an Idempotency-Key header to avoid creating a job twice. The same key returns the original job with HTTP 200 for as long as that job exists. Keys are per workspace and matched on the key alone: a different body with the same key still returns the original job, once that body passes validation. dry_run requests are never deduplicated.

Dry run

With "dry_run": true the request is checked, priced and returned with HTTP 200. Nothing is created, so there is no job_id.

{
  "data": {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "platform": "youtube",
    "duration_seconds": null,
    "credits_estimated": 7,
    "balance": 850,
    "would_exceed_balance": false,
    "note": "duration_unresolved"
  },
  "meta": { "request_id": "req_xyz789" }
}

The length isn't known before the video is fetched, so the estimate assumes your plan's longest video and note says duration_unresolved. would_exceed_balance is a warning, not a refusal. A dry run works on an empty balance too.

GET /v1/jobs/:id

A job, with results once it has completed.

curl https://api.netraflow.com/v1/jobs/job_abcdefghij123456 \
  -H "X-Api-Key: sk_live_your_key_here"

{
  "data": {
    "job_id": "job_abcdefghij123456",
    "status": "completed",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "platform": "youtube",
    "capabilities": ["transcription", "summary"],
    "language": null,
    "video_title": "Never Gonna Give You Up",
    "video_duration_seconds": 212,
    "video_thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "credits_estimated": 17,
    "credits_charged": 6,
    "processing_seconds": 43,
    "results": {
      "transcription": {
        "text": "...",
        "segments": [{ "start": 0.0, "end": 5.2, "text": "..." }],
        "language": "en",
        "duration_seconds": 212.0,
        "word_count": 1250
      },
      "summary": {
        "text": "...",
        "key_topics": ["topic1", "topic2"]
      }
    },
    "return_proof": true,
    "follow_id": null,
    "created_at": "2026-04-03T12:00:00.000Z",
    "started_at": "2026-04-03T12:00:01.000Z",
    "completed_at": "2026-04-03T12:00:45.000Z"
  },
  "meta": { "request_id": "req_abc456" }
}

A failed job has error: { code, message } instead of results. processing_seconds is how long the job took to process, null until it settles. It doesn't change what you pay.

Result keys

results has one key per capability: transcription, summary, brands, metadata, objects, and query_results for your questions. Each is described on its capability page. Also:

results can hold keys you didn't ask for: a job on a link can return the video's metadata, and a brands job returns the transcription it listened to. Neither adds to the cost.

When one capability cannot run

When brand detection or object tracking is unavailable, a job that asked only for it fails with a job failure code. A job that asked for more completes with the rest, and:

• the missing capability's key is absent from results (an empty list would mean "none in the video");
• results.meta.failed_capabilities lists it, with the code and message a failed job would carry;
• nothing it did is charged.

"meta": {
  "failed_capabilities": [
    {
      "capability": "brands",
      "code": "BRAND_DETECTION_UNAVAILABLE",
      "message": "Brand detection is temporarily unavailable. Please try again."
    }
  ]
}

Submit the video again with just that capability to fill the gap. The job.completed webhook carries the same list.

What you are charged for

credits_charged is a flat $0.10 per video plus a usage charge for the analysis your job actually ran. 1 credit is $0.10, and the total is rounded up to a whole credit. Every amount in the API is in credits.

The usage part follows the work, not the length: brand detection on a 30-second clip can cost more than transcribing a long video. It is measured on every run, so the same request can cost a little differently twice.

credits_charged is null until the job settles, and whenever nothing was billed.

credits_estimated is a guardrail, not a quote: the settled charge can land either side of it, usually below. max_credits is checked against the estimate once the real length is known. It does not cap the settled charge.

Job status values

A held job fires a job.held webhook with credits_needed and balance. A pending job with CREDITS_SET_ASIDE is one your balance covers, but not beside the credits your running jobs have set aside. A submit with nothing left to spend is refused with INSUFFICIENT_CREDITS (402).

Progress

While a job is processing, progress shows where it is. Stages run in order: ingestion, transcription, analysis, merging.

"progress": {
  "stage": "analysis",
  "stages_completed": ["ingestion", "transcription"],
  "stages_remaining": ["merging"]
}

A stage the job doesn't need is listed in stages_completed once the job is past it.

GET /v1/jobs

Your jobs, newest first, with cursor pagination.

next_cursor is null on the last page. A bad cursor or date returns VALIDATION_FAILED (422).

curl "https://api.netraflow.com/v1/jobs?status=completed&limit=5" \
  -H "X-Api-Key: sk_live_your_key_here"

{
  "data": [
    {
      "job_id": "job_abcdefghij123456",
      "status": "completed",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "platform": "youtube",
      "capabilities": ["transcription", "summary"],
      "video_title": "Never Gonna Give You Up",
      "credits_estimated": 5,
      "credits_charged": 3,
      "follow_id": null,
      "created_at": "2026-04-03T12:00:00.000Z",
      "completed_at": "2026-04-03T12:00:45.000Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "MjAyNi0wNC0wM1QxMjowMDowMC4wMDBafGpvYl9hYmNkZWZnaGlqMTIzNDU2"
  },
  "meta": { "request_id": "req_xyz789" }
}

List items

A list item is a summary: job_id, status, url (or the upload_key), platform, capabilities, video_title, credits_estimated, credits_charged, follow_id, created_at and completed_at, each as on GET /v1/jobs/:id. Fetch the job for its results.

follow_id is null on a job you submitted, and names the follow that created it otherwise. Follows are set up in the console or over MCP; ?follow_id=any lists everything they caught.

POST /v1/jobs/:id/cancel

Cancel a pending, processing or held job. Returns HTTP 200 with the job as it stands right after the cancel.

curl -X POST https://api.netraflow.com/v1/jobs/job_abcdefghij123456/cancel \
  -H "X-Api-Key: sk_live_your_key_here"

{
  "data": {
    "job_id": "job_abcdefghij123456",
    "status": "cancelled",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "platform": "youtube",
    "capabilities": ["transcription", "summary"],
    "language": null,
    "video_title": null,
    "video_duration_seconds": null,
    "video_thumbnail_url": null,
    "credits_estimated": 5,
    "credits_charged": null,
    "processing_seconds": null,
    "return_proof": true,
    "follow_id": null,
    "created_at": "2026-04-03T12:00:00.000Z",
    "started_at": "2026-04-03T12:00:01.000Z",
    "completed_at": null
  },
  "meta": { "request_id": "req_xyz789" }
}

credits_charged is still null in the response. A running job is charged for the work it did a few seconds later: read it with GET /v1/jobs/:id, or wait for the job.cancelled webhook, which carries the final charge.

A job in a batch can't be cancelled on its own: cancel the batch with POST /v1/batch/:id/cancel. Cancelling a job that already ended, or is in a batch, returns JOB_NOT_CANCELLABLE (409).

Authentication and scopes

Every request needs an X-Api-Key header. Create keys in the console under API keys (owners and managers).

Every key gets all three scopes today, so treat any key as one that can spend credits. A key without a scope an endpoint needs returns INSUFFICIENT_SCOPE (403).

Error codes

Every error has the same shape. Quote meta.request_id when you contact support.

{
  "error": {
    "code": "INVALID_QUERY",
    "message": "queries[0] looks like an attempt to change the model's instructions. Ask about the video instead.",
    "details": { "index": 0 }
  },
  "meta": { "request_id": "req_xyz789" }
}

details comes with three codes only:

A list longer than the every-plan maximum on Limits fails with VALIDATION_FAILED before the plan limit is checked.

Successful responses carry X-RateLimit-Limit (your burst) and X-RateLimit-Remaining. Error responses don't.

Job failure codes

A failed job carries one of these in error.code, inside a 200 from GET /v1/jobs/:id. A failed job is never charged and never retried for you.

BRAND_DETECTION_UNAVAILABLE and OBJECT_DETECTION_UNAVAILABLE fail the job only when that capability is all it asked for; otherwise see When one capability cannot run. A brands job that runs short completes with what it found and meta.brand_detection_degraded: true, and is charged for that work. TIMEOUT always fails the whole job.

CREDITS_SET_ASIDE and CONCURRENT_LIMIT_REACHED on a pending job are not failures: see Job status values.