API 레퍼런스

Batch Processing 엔드포인트에 대한 REST API 레퍼런스입니다.

빠른 링크:

데이터 수집 (비디오, 단일 이미지, 이미지)
배치 상태 확인 (항목 수, 샤드 상세 정보)
작업 시작
작업 진행 상황 모니터링 (작업 상태, 단계, 태스크)
결과 내보내기 (출력 파트, 다운로드 URL)
Webhook 알림

데이터 수집

비디오 업로드

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 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

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
  }
}

배치 상태 확인

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
}

샤드 업로드 상세 정보 확인

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 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"
}

작업 진행 상황 모니터링

작업 상태 가져오기

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

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 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"
}

결과 내보내기

출력 파트 목록

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"
    }
  ]
}

다운로드 URL 목록

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 알림

상태를 폴링하는 대신, webhook을 사용하여 수집 또는 처리가 완료되면 알림을 받을 수 있습니다. CLI Usage 에서 webhook 구성 및 페이로드 형식을 확인하세요.

PreviousBatch Processing NextCLI 사용

Last updated 5 days ago

Was this helpful?

hashtag데이터 수집

hashtag비디오 업로드

hashtagUpload a video

hashtag이미지 업로드

hashtagUpload a single image

hashtag이미지 일괄 업로드

hashtagBulk upload images

hashtag배치 상태 확인

hashtagGet batch item count

hashtag샤드 업로드 상세 정보 확인

hashtagList batch shards

hashtag작업 시작

hashtagStart a batch processing job

hashtag작업 진행 상황 모니터링

hashtag작업 상태 가져오기

hashtagGet job status

hashtag작업 단계 목록

hashtagList job stages

hashtag단계 태스크 목록

hashtagList tasks for a stage

hashtag결과 내보내기

hashtag출력 파트 목록

hashtagList output batch parts

hashtag다운로드 URL 목록

hashtagList download URLs

hashtagWebhook 알림

데이터 수집

비디오 업로드

Upload a video

이미지 업로드

Upload a single image

이미지 일괄 업로드

Bulk upload images

배치 상태 확인

Get batch item count

샤드 업로드 상세 정보 확인

List batch shards

작업 시작

Start a batch processing job

작업 진행 상황 모니터링

작업 상태 가져오기

Get job status

작업 단계 목록

List job stages

단계 태스크 목록

List tasks for a stage

결과 내보내기

출력 파트 목록

List output batch parts

다운로드 URL 목록

List download URLs

Webhook 알림