API Reference

REST API reference for Batch Processing endpoints.

Quick Links:

Ingest Data (video, single image, images)
Check Batch Status (item count, shard details)
Start a Job
Monitor Job Progress (job status, stages, tasks)
Export Results (output parts, download URLs)
Webhook Notifications

Ingest Data

Upload Video

Upload a video

post

Request a signed URL to upload a video file. After receiving the response, PUT the video to the uploadURL with the provided extensionHeaders.

Path parameters

workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$

Query parameters

api_keystringRequired

Your Roboflow API key.

fileNamestringRequired

Name of the video file (e.g. my_video.mp4).

Responses

200

Signed URL details for uploading the video.

application/json

statusstringOptionalExample: ok

post

/data-staging/v1/external/{workspace}/batches/{batch_id}/upload/video

POST /data-staging/v1/external/{workspace}/batches/{batch_id}/upload/video?api_key=text&fileName=text HTTP/1.1
Host: api.roboflow.com
Accept: */*

200

Signed URL details for uploading the video.

{
  "status": "ok",
  "signedURLDetails": {
    "uploadURL": "text",
    "method": "PUT",
    "extensionHeaders": {
      "Content-Type": "application/octet-stream",
      "x-goog-content-length-range": "1,1073741824"
    },
    "maxFileSize": 1073741824
  }
}

Upload Image

Upload a single image

post

Upload a single image via multipart form data. Best for batches up to 5,000 images.

Note: Single-image and bulk uploads cannot be combined for the same batch.

Path parameters

workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$

Query parameters

api_keystringRequired

Your Roboflow API key.

fileNamestringRequired

Name of the image file.

Body

filestring · binaryOptional

The image file to upload.

Responses

200

Image uploaded successfully.

application/json

statusstringOptionalExample: ok

post

/data-staging/v1/external/{workspace}/batches/{batch_id}/upload/image

POST /data-staging/v1/external/{workspace}/batches/{batch_id}/upload/image?api_key=text&fileName=text HTTP/1.1
Host: api.roboflow.com
Content-Type: multipart/form-data
Accept: */*
Content-Length: 17

{
  "file": "binary"
}

200

Image uploaded successfully.

{
  "status": "ok"
}

Bulk Upload Images

Bulk upload images

post

Request a signed URL for uploading a .tar archive of images. Recommended for batches exceeding 5,000 images. Bundle up to 500 images per archive.

The response contains a signed URL and extension headers. Pack images into a .tar archive and PUT it to the signed URL.

Note: Bulk and single-image uploads cannot be combined for the same batch.

When performing bulk ingestion, data is indexed in the background. There may be a short delay before all data is available.

Path parameters

workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$

Query parameters

api_keystringRequired

Your Roboflow API key.

Responses

200

Signed URL details for uploading a tar archive.

application/json

statusstringOptionalExample: ok

post

/data-staging/v1/external/{workspace}/batches/{batch_id}/bulk-upload/image-files

POST /data-staging/v1/external/{workspace}/batches/{batch_id}/bulk-upload/image-files?api_key=text HTTP/1.1
Host: api.roboflow.com
Accept: */*

200

Signed URL details for uploading a tar archive.

{
  "status": "ok",
  "signedURLDetails": {
    "shardId": "123e4567-e89b-12d3-a456-426614174000",
    "uploadURL": "text",
    "method": "PUT",
    "extensionHeaders": {
      "Content-Type": "application/x-tar",
      "x-goog-content-length-range": "1,536870912"
    },
    "maxNumberOfImages": 500,
    "maxShardSize": 536870912
  }
}

Check Batch Status

Get batch item count

get

Returns the count of ingested items in a batch. Use this to verify all data has been ingested before starting a job.

Path parameters

workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$

Query parameters

api_keystringRequired

Your Roboflow API key.

Responses

200

Batch item count.

application/json

statusstringOptionalExample: ok

countintegerOptional

Number of items in the batch.

Example: 42

get

/data-staging/v1/external/{workspace}/batches/{batch_id}/count

GET /data-staging/v1/external/{workspace}/batches/{batch_id}/count?api_key=text HTTP/1.1
Host: api.roboflow.com
Accept: */*

200

Batch item count.

{
  "status": "ok",
  "count": 42
}

Check Shard Upload Details

List batch shards

get

Returns shard details for a bulk-upload batch. Paginated — use nextPageToken from the response to fetch subsequent pages.

Path parameters

workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$

Query parameters

api_keystringRequired

Your Roboflow API key.

nextPageTokenstringOptional

Pagination token from a previous response.

Responses

200

Paginated list of batch shards.

application/json

statusstringOptionalExample: ok

shardsobject[]Optional

List of shard objects.

nextPageTokenstring · nullableOptional

Token for fetching the next page of results. null if no more pages.

get

/data-staging/v1/external/{workspace}/batches/{batch_id}/shards

GET /data-staging/v1/external/{workspace}/batches/{batch_id}/shards?api_key=text HTTP/1.1
Host: api.roboflow.com
Accept: */*

200

Paginated list of batch shards.

{
  "status": "ok",
  "shards": [
    {}
  ],
  "nextPageToken": "text"
}

Start a Job

Start a batch processing job

post

Start a batch processing job that runs a Workflow against staged data.

Job ID constraints: Lowercase letters, digits, hyphens, and underscores only. Maximum 20 characters.

Path parameters

workspacestringRequired

Your Roboflow workspace identifier.

job_idstring · max: 20Required

Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$

Query parameters

api_keystringRequired

Your Roboflow API key.

Body

typestring · enumRequired

Job type.

Possible values:

processingTimeoutSecondsintegerOptional

Maximum cumulative machine runtime in seconds across all parallel workers.

Default: 3600

notificationsURLstring · uriOptional

Webhook URL for job completion notifications. Custom webhook headers are not yet supported. The only header sent is Authorization: Bearer rf_{workspace_id}.

Responses

200

Job started successfully.

application/json

statusstringOptionalExample: ok

post

/batch-processing/v1/external/{workspace}/jobs/{job_id}

POST /batch-processing/v1/external/{workspace}/jobs/{job_id}?api_key=text HTTP/1.1
Host: api.roboflow.com
Content-Type: application/json
Accept: */*
Content-Length: 415

{
  "type": "simple-image-processing-v1",
  "jobInput": {
    "type": "staging-batch-input-v1",
    "batchId": "text"
  },
  "computeConfiguration": {
    "type": "compute-configuration-v2",
    "machineType": "cpu",
    "workersPerMachine": 4
  },
  "processingTimeoutSeconds": 3600,
  "processingSpecification": {
    "type": "workflows-processing-specification-v1",
    "workspace": "text",
    "workflowId": "text",
    "aggregationFormat": "jsonl"
  },
  "notificationsURL": "https://example.com"
}

200

Job started successfully.

{
  "status": "ok"
}

Monitor Job Progress

Get Job Status

Get job status

get

Returns the current status of a batch processing job.

Path parameters

workspacestringRequired

Your Roboflow workspace identifier.

job_idstring · max: 20Required

Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$

Query parameters

api_keystringRequired

Your Roboflow API key.

Responses

200

Job status details.

application/json

statusstringOptionalExample: ok

jobStatusstringOptional

Current job status (e.g. pending, processing, completed, failed).

progressnumberOptional

Processing progress as a fraction between 0 and 1.

get

/batch-processing/v1/external/{workspace}/jobs/{job_id}

GET /batch-processing/v1/external/{workspace}/jobs/{job_id}?api_key=text HTTP/1.1
Host: api.roboflow.com
Accept: */*

200

Job status details.

{
  "status": "ok",
  "jobStatus": "text",
  "progress": 1
}

List Job Stages

List job stages

get

Returns the list of stages for a job. Each job typically has processing and export stages, each producing an output batch.

Path parameters

workspacestringRequired

Your Roboflow workspace identifier.

job_idstring · max: 20Required

Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$

Query parameters

api_keystringRequired

Your Roboflow API key.

Responses

200

List of job stages.

application/json

statusstringOptionalExample: ok

stagesobject[]Optional

List of stage objects. Each stage has an ID and an output batch ID.

get

/batch-processing/v1/external/{workspace}/jobs/{job_id}/stages

GET /batch-processing/v1/external/{workspace}/jobs/{job_id}/stages?api_key=text HTTP/1.1
Host: api.roboflow.com
Accept: */*

200

List of job stages.

{
  "status": "ok",
  "stages": [
    {}
  ]
}

List Stage Tasks

List tasks for a stage

get

Returns the list of tasks for a specific job stage. Paginated — use nextPageToken from the response to fetch subsequent pages.

Path parameters

workspacestringRequired

Your Roboflow workspace identifier.

job_idstring · max: 20Required

Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$

stage_idstringRequired

The stage identifier.

Query parameters

api_keystringRequired

Your Roboflow API key.

nextPageTokenstringOptional

Pagination token from a previous response.

Responses

200

Paginated list of tasks.

application/json

statusstringOptionalExample: ok

tasksobject[]Optional

List of task objects.

nextPageTokenstring · nullableOptional

Token for fetching the next page of results. null if no more pages.

get

/batch-processing/v1/external/{workspace}/jobs/{job_id}/stages/{stage_id}/tasks

GET /batch-processing/v1/external/{workspace}/jobs/{job_id}/stages/{stage_id}/tasks?api_key=text HTTP/1.1
Host: api.roboflow.com
Accept: */*

200

Paginated list of tasks.

{
  "status": "ok",
  "tasks": [
    {}
  ],
  "nextPageToken": "text"
}

Export Results

List Output Parts

List output batch parts

get

Lists the parts of an output batch. Use the export stage output batch for compressed results.

Path parameters

workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$

Query parameters

api_keystringRequired

Your Roboflow API key.

Responses

200

List of batch parts.

application/json

statusstringOptionalExample: ok

get

/data-staging/v1/external/{workspace}/batches/{batch_id}/parts

GET /data-staging/v1/external/{workspace}/batches/{batch_id}/parts?api_key=text HTTP/1.1
Host: api.roboflow.com
Accept: */*

200

List of batch parts.

{
  "status": "ok",
  "parts": [
    {
      "partName": "text"
    }
  ]
}

List Download URLs

List download URLs

get

Returns paginated download URLs for files in a batch part.

Path parameters

workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$

Query parameters

api_keystringRequired

Your Roboflow API key.

nextPageTokenstringOptional

Pagination token from a previous response.

partNamestringOptional

Filter by part name (from the list parts response).

Responses

200

Paginated list of download URLs.

application/json

statusstringOptionalExample: ok

nextPageTokenstring · nullableOptional

Token for fetching the next page of results. null if no more pages.

get

/data-staging/v1/external/{workspace}/batches/{batch_id}/list

GET /data-staging/v1/external/{workspace}/batches/{batch_id}/list?api_key=text HTTP/1.1
Host: api.roboflow.com
Accept: */*

200

Paginated list of download URLs.

{
  "status": "ok",
  "filesMetadata": [
    {
      "downloadURL": "text",
      "fileName": "text",
      "partName": "text",
      "shardId": "text",
      "contentType": "text",
      "nestedContentType": "text"
    }
  ],
  "nextPageToken": "text"
}

Webhook Notifications

Instead of polling for status, you can use webhooks to get notified when ingestion or processing completes. See CLI Usage for webhook configuration and payload formats.

PreviousBatch Processing NextCLI Usage

Last updated 5 days ago

Was this helpful?

hashtagIngest Data

hashtagUpload Video

hashtagUpload a video

hashtagUpload Image

hashtagUpload a single image

hashtagBulk Upload Images

hashtagBulk upload images

hashtagCheck Batch Status

hashtagGet batch item count

hashtagCheck Shard Upload Details

hashtagList batch shards

hashtagStart a Job

hashtagStart a batch processing job

hashtagMonitor Job Progress

hashtagGet Job Status

hashtagGet job status

hashtagList Job Stages

hashtagList job stages

hashtagList Stage Tasks

hashtagList tasks for a stage

hashtagExport Results

hashtagList Output Parts

hashtagList output batch parts

hashtagList Download URLs

hashtagList download URLs

hashtagWebhook Notifications

Ingest Data

Upload Video

Upload a video

Upload Image

Upload a single image

Bulk Upload Images

Bulk upload images

Check Batch Status

Get batch item count

Check Shard Upload Details

List batch shards

Start a Job

Start a batch processing job

Monitor Job Progress

Get Job Status

Get job status

List Job Stages

List job stages

List Stage Tasks

List tasks for a stage

Export Results

List Output Parts

List output batch parts

List Download URLs

List download URLs

Webhook Notifications