APIリファレンス

バッチ処理エンドポイントのREST APIリファレンス。

クイックリンク：

データを取り込む（動画、単一画像、画像）
バッチのステータスを確認（アイテム数、シャードの詳細）
ジョブを開始
Jobの進行状況を監視（Jobのステータス、ステージ、タスク）
結果をエクスポート（出力パーツ、ダウンロード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
}

Shardのアップロード詳細を確認

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

Jobの進行状況を監視

Jobのステータスを取得

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
}

Jobのステージを一覧表示

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の使用方法について、webhookの設定とペイロード形式を参照してください。

Previousバッチ処理 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

hashtagShardのアップロード詳細を確認

hashtagList batch shards

hashtagジョブを開始

hashtagStart a batch processing job

hashtagJobの進行状況を監視

hashtagJobのステータスを取得

hashtagGet job status

hashtagJobのステージを一覧表示

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

Shardのアップロード詳細を確認

List batch shards

ジョブを開始

Start a batch processing job

Jobの進行状況を監視

Jobのステータスを取得

Get job status

Jobのステージを一覧表示

List job stages

ステージのタスクを一覧表示

List tasks for a stage

結果をエクスポート

出力パーツを一覧表示

List output batch parts

ダウンロードURLを一覧表示

List download URLs

Webhook通知