Skip to Content
API referenceBatches

Batches

Bulk cohorts of scenes uploaded together, plus the workspace ledger that rolls up yield, quality, and cost. Reads need scenes:read; writes need scenes:write.

List batches with aggregated scene counts.

scenes:read
GET/v1/batches
Response fields
id
string
Batch ID.
name
string
Batch name.
tier
"TIER_1" | "TIER_2" | "TIER_3"
Batch tier.
status
string
Batch status.
scenesTotal
integer
Total scenes in the batch.
scenesCompleted
integer
Scenes finished processing.
createdAt
string (ISO)
Created timestamp.
GET/v1/batches
Request
GET /v1/batches
Response
Press Run request to see the response

Get one batch with its scenes.

scenes:read
GET/v1/batches/{id}
Parameters
id
string · required
Batch ID.
Response fields
id
string
Batch ID.
name
string
Batch name.
tier
"TIER_1" | "TIER_2" | "TIER_3"
Batch tier.
status
string
Batch status.
scenes
object[]
Scenes in the batch.

Workspace ledger — 30d summary tiles + per-batch cohort rows.

scenes:read
GET/v1/batches/ledger
Response fields
summary
object
{ totalBatches30d, scenesShipped30d, yieldAvg, qualityAvg, costSpent30d, costPerScene, gpuHours30d, flaggedOpen }.
batches
object[]
Per-batch cohort rows.

Batch detail: lineage, quality histogram, failures, scene grid.

scenes:read
GET/v1/batches/{id}/detail
Parameters
id
string · required
Batch ID.
Response fields
meta
object
Batch metadata.
lineage
object
Batch lineage/provenance.
qualityHist
object[]
Quality-score histogram buckets.
failures
object[]
Failed scenes with reasons.
scenes
object[]
Scene grid.
totalSceneCount
integer
Total scenes in the batch.

Recent activity events for a batch.

scenes:read
GET/v1/batches/{id}/events
Parameters
id
string · required
Batch ID.
limit
integer
Max events (default 4, max 20).
Response fields
id
string
Event ID.
kind
string
Event kind.
text
string
Human-readable text.
actor
string
Who triggered it.
occurredAt
string (ISO)
When it happened.

Create a batch from existing scene IDs.

scenes:write
POST/v1/batches
Console roles: OWNER, DIRECTOR
Request body
name
string · required
Batch name.
tier
"TIER_1" | "TIER_2" | "TIER_3" · required
Batch tier.
sceneIds
string[] · required
Existing scene IDs to group.
Response fields
id
string
Batch ID.
name
string
Batch name.
tier
"TIER_1" | "TIER_2" | "TIER_3"
Batch tier.
status
string
Batch status.
scenesCount
integer
Scenes in the batch.
createdAt
string (ISO)
Created timestamp.

Create a batch with up to 5000 scenes; validates credits (402 if short).

scenes:write
POST/v1/batches/bulk
Console roles: OWNER, DIRECTOR
Request body
name
string · required
Batch name.
tier
"TIER_1" | "TIER_2" | "TIER_3" · required
Batch tier.
scenes
object[] · required
1–5000 scenes: { filename, url?, tier?, sceneName? }.
Response fields
id
string
Batch ID.
name
string
Batch name.
tier
"TIER_1" | "TIER_2" | "TIER_3"
Batch tier.
status
string
Batch status.
scenesCount
integer
Scenes created.
creditsCharged
integer
Credits debited.
createdAt
string (ISO)
Created timestamp.

Cancel a running batch.

scenes:write
POST/v1/batches/{id}/cancel
Console roles: OWNER, DIRECTOR
Parameters
id
string · required
Batch ID.

Returns the updated batch with status CANCELLED.

Hard-delete a batch and all its scenes (cascade).

scenes:write
DELETE/v1/batches/{id}
Console roles: OWNER, DIRECTOR
Parameters
id
string · required
Batch ID.
Response fields
deleted
boolean
True if deleted.
deletedSceneCount
integer
Scenes removed in the cascade.
Last updated on
§2257 recordsSites