Jobs

POST /v1/jobs

Create a new video analysis job. The API validates the request, estimates credits, and queues the job for processing.

Request body

Provide exactly one source: either url or upload_key.

Idempotency

Include an Idempotency-Key header to prevent duplicate job creation. If a matching key is found within the 48-hour deduplication window, the original job is returned with HTTP 200 — no new job is created. After 48 hours the key expires and a new job would be created.

Keys are scoped to your workspace and matched on the key alone: reusing a key with a different body returns the original job, not a new one. dry_run requests are never deduplicated.

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_abc123",
    "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": 17,
    "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" }
}

Jobs created with queries, brands, surfaces, objects or from_job echo those values back in the response.

GET /v1/jobs/:id

Retrieve a job by ID, including results when completed.

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

{
  "data": {
    "job_id": "job_abc123",
    "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": 5,
    "credits_charged": 3,
    "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" }
}

Result keys

results carries one key per produced capability — transcription, summary, brands, metadata, objects — plus:

Failed jobs carry error: { code, message } instead of results.

What you are charged for

credits_charged has two parts: a usage charge for the analysis your job actually ran, plus a flat $0.10 per minute of processing time — the wall-clock time your job occupied a worker, reported as processing_seconds.

Processing time is not the same as video_duration_seconds, and pricing on the video's length would be the wrong number. A 27-minute YouTube video with publisher captions is transcribed without downloading anything and finishes in seconds; a 30-second clip put through full brand detection extracts frames, reads every logo it finds, and works for minutes. You pay for the second one.

processing_seconds is null until the job settles, and stays null on jobs that never finish — failed, cancelled, or held. Queue time is never billed: the clock starts when a worker picks the job up (started_at), not when you submit it. A retry after an infrastructure failure starts a fresh clock, so you are never billed twice for the same work.

Job status values

Progress

The progress object is included only while status is "processing". Pipeline stages run in order: ingestion → transcription → analysis → merging.

GET /v1/jobs

List jobs with cursor-based pagination.

Query parameters

Pass next_cursor from the previous response verbatim. Results are ordered newest-first by created_at, then id. next_cursor is null on the last page, and a malformed cursor returns VALIDATION_FAILED (422).

Every job carries follow_id — null for a job you submitted, otherwise the Follow that created it. Together with the filter above, that is the whole read side of Follows: a follow-created job is an ordinary job, so GET /v1/jobs?follow_id=any answers "what did my follows catch this week" with no extra endpoint. Follows themselves are set up in the console; there is no POST /v1/follows.

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

{
  "data": [
    {
      "job_id": "job_abc123",
      "status": "completed",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "platform": "youtube",
      "credits_estimated": 5,
      "follow_id": null,
      "created_at": "2026-04-03T12:00:00.000Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6IjEyMyJ9"
  },
  "meta": { "request_id": "req_xyz789" }
}

POST /v1/jobs/:id/cancel

Cancel a pending, processing, or (unbatched) held job. Jobs belonging to a batch must be cancelled via POST /v1/batch/:id/cancel.

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

{
  "data": {
    "job_id": "job_abc123",
    "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": 2,
    "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" }
}

Returns JOB_NOT_FOUND (404) if the job doesn't exist, or JOB_NOT_CANCELLABLE (409) if the job is already in a terminal state.

Authentication and scopes

Every request needs an X-Api-Key header. Keys carry scopes:

A key without the required scope returns INSUFFICIENT_SCOPE (403).

Error codes

These are returned synchronously, as error.code with the listed HTTP status.

Job failure codes

These appear as error.code inside a 200 response from GET /v1/jobs/:id when a job fails — they are not HTTP statuses.

Rate limiting

Requests are rate-limited per plan using a token bucket: a bucket of burst_limit tokens that refills continuously at your plan's sustained rate. An idle client can spend a full burst at once; sustained traffic settles at the per-minute rate.

Successful responses carry X-RateLimit-Limit (the burst capacity) and X-RateLimit-Remaining. When rate-limited you get HTTP 429 with Retry-After: 60; the X-RateLimit-* headers are not present on error responses.