Jobs
Create, retrieve, list, and cancel video analysis 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
Prop
Type
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.
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"],
"return_proof": true
}'{
"data": {
"job_id": "job_abc123",
"status": "pending",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"platform": "youtube",
"capabilities": ["transcription", "summary", "brands"],
"credits_estimated": 17,
"credits_charged": null,
"return_proof": true,
"created_at": "2026-04-03T12:00:00.000Z",
"started_at": null,
"completed_at": null
},
"meta": { "request_id": "req_xyz789" }
}Response headers include Location: /v1/jobs/job_abc123 and Retry-After: 30.
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"],
"credits_estimated": 5,
"credits_charged": 3,
"progress": {
"stage": "merging",
"stages_completed": ["ingestion", "transcription", "analysis"],
"stages_remaining": []
},
"results": {
"transcription": {
"text": "...",
"segments": [{ "start": 0.0, "end": 5.2, "text": "..." }],
"language": "en",
"duration_seconds": 438.0,
"word_count": 1250
},
"summary": {
"text": "...",
"key_topics": ["topic1", "topic2"]
}
},
"return_proof": false,
"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" }
}Job status values
Prop
Type
Progress
The progress object is included when status is "processing". Pipeline stages run in order: ingestion → transcription → analysis → merging.
GET /v1/jobs
List jobs with cursor-based pagination.
Query parameters
Prop
Type
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,
"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 or processing job.
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"
},
"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.
Error codes
Rate limiting
Requests are rate-limited per plan on a sliding 1-minute window.
Prop
Type
When rate-limited, the response includes a Retry-After: 60 header. The current limit is returned on every response as X-RateLimit-Limit.