TubeExtract
Start free
API reference/Other endpoints

Jobs, usage, schemas, webhooks and keys API

List jobs, read credit usage, manage versioned saved schemas, register webhook endpoints and create or revoke API keys.

Everything besides submitting and reading a job. The same API key, the same per-minute limit and the same error codes apply.

Listing jobs

GET /v1

Field
Type
Required
Description
statusquerynorunning for jobs with a video still queued or processing, succeeded for jobs where every video is done, failed for jobs with at least one failed video.
searchquerynoMatches the start of a job id, a video's id, or a YouTube video id.
limitqueryno1 to 100. Defaults to 25.
offsetquerynoDefaults to 0.
200
{
"data": [
{
"job_id": "8f2c1e40-91a3-4b7e",
"status": "done",
"schema": "restaurants-v2",
"videos": 3,
"credits_charged": 420,
"counts": {
"queued": 0,
"processing": 0,
"done": 3,
"failed": 0
},
"created_at": "2026-09-14 09:12:03",
"completed_at": "2026-09-14 09:12:58",
"results": []
}
],
"pagination": {
"total": 41,
"limit": 25,
"offset": 0,
"has_more": true
}
}
NOTE
The list never carries rows and never hands anything over, so paging through history is safe. results is null while a job is running and an empty list once it has settled; read the job itself to collect.

Usage

GET /v1/usage

200
{
"credits": {
"balance": 23660,
"used_this_cycle": 1340,
"cycle_allowance": 25000,
"hard_cap": null
},
"cycle": {
"started_at": "2026-09-01 00:00:00",
"ends_at": "2026-10-01 00:00:00"
},
"plan": {
"id": "starter",
"name": "Starter",
"requests_per_minute": 30
},
"jobs": {
"queued": 0,
"processing": 1,
"done": 12,
"failed": 2,
"total": 15
},
"videos_processed": 12,
"failures_by_code": {
"no_captions": 2
},
"daily": [
{
"date": "2026-09-14",
"credits": 420
}
]
}

daily covers the last 14 days, one entry per day, credits spent. hard_cap is the ceiling you set on the dashboard overview, or null.

Saved schemas

A saved schema can be used on POST /v1 as schema_id. Schemas are versioned: editing publishes a new version and never changes an old one, so a finished job always describes what it actually ran.

GET /v1/schemas

Every schema in the workspace at its latest version, each with id, name, description, version, label (such as restaurants-v2), schema and created_at, inside data.

POST /v1/schemas

Field
Type
Required
Description
namestringyesLowercase letters, numbers and hyphens, up to 64 characters. Unique in the workspace.
descriptionstringnoUp to 280 characters.
schemaobjectyesThe same shape as schema on POST /v1: columns, or a template with descriptions.
201
{
"id": "3c9d2a61-0f4e-4b7a",
"name": "restaurants",
"version": 1
}

GET /v1/schemas/{id}

One schema with latest_version and every version it has had, each with its schema and created_at. An unknown id is 404 schema_not_found.

POST /v1/schemas/{id}/versions

Publishes a new version. The body takes schema and an optional description, and answers 201 with the id and the new version. Jobs submitted with this schema_id and no schema_version use it from now on.

Webhook endpoints

Webhooks are a paid-plan feature: creating an endpoint on Free answers 403 plan_limit. What gets delivered is on webhook payloads.

GET /v1/webhooks

Each endpoint’s id, url, events, disabled and created_at, inside data. Signing secrets are not listed; they are on the webhooks screen.

POST /v1/webhooks

Field
Type
Required
Description
urlstringyesAn https:// URL.
eventsstring[]noAny of job.completed, job.failed, batch.completed. All three when left out.
201
{
"id": "e5a0b4c8-2d17-4f93",
"url": "https://example.com/hooks/tubeextract",
"secret": "whsec_…"
}

DELETE /v1/webhooks/{id}

Removes the endpoint. Answers 204 with no body.

API keys

GET /v1/keys

Every key in the workspace, revoked ones included, with id, label, masked_key, environment, last_used_at, revoked_at and created_at, inside data. The full key is never shown again after creation.

POST /v1/keys

Field
Type
Required
Description
labelstringnoUp to 100 characters.
notestringnoUp to 200 characters.
environmentstringnolive or test, which sets the key’s prefix. Both bill the same way.
201
{
"id": "71b6f0d3-8a2e-4c55",
"key": "tbx_live_…",
"label": "production"
}
CAREFUL
key is in this response and nowhere else, ever. Only a hash is stored. Over the plan’s key allowance the call answers 403 plan_limit.

DELETE /v1/keys/{id}

Revokes the key immediately. Answers 204. Revoking cannot be undone.

Was this page useful?Tell us what was missing
Previous
/v1/{job_id}
Next
Error codes