For agents: This skill is authored in
roboflow/computer-vision-skills
. If your client already has it loaded as a skill (for example from a Roboflow plugin), use that copy. The
skill://roboflow/<name>/SKILL.md
MCP resources serve the same skills for clients that don't have them loaded.
Batch Processing
Run a Roboflow Workflow over a very large set of images or videos on
Roboflow's autoscaling compute. Every job processes a temporary Data Staging
batch; the two input paths differ only in who fills that batch:
- Asset Library job — the files are already in Roboflow. You hand the
platform a selection and it selects and stages them for you.
- Staged job — the files are outside Roboflow (local disk, cloud bucket,
references file), so you stage them yourself with the inference-cli: only
your machine and credentials can reach them. Nothing is imported into the
workspace, and staged data expires after ~7 days.
Which path? Three questions
- Are the files already in Roboflow (Asset Library)? Call
batch_processing_asset_library_job_create
with a stable idempotency key
and exactly one selection: , , or . The
platform performs access checks, selects the files, stages them, verifies
Workflow compatibility, bills, and registers the durable job. Poll the
returned with batch_processing_asset_library_task_get
until the
task is terminal; then monitor its with .
- Files outside Roboflow, and you only want the outputs? Stage them
yourself and drive the run with +
as described below (the classic ETL shape: nothing
lands in the workspace). Staging and result export must run on the machine
that can access the files.
- Files outside Roboflow that you want INSIDE it (labeling, curation,
training)? That is an import, not a batch processing job: mirror the
bucket with a datasource (, see the
skill). Once mirrored, the files are Asset Library images, so if you also
want bulk predictions, run an Asset Library job over them (the classic ELT
shape: load first, then transform).
"Datasource" and "bucket mirror" are one thing: a datasource is the
user-facing name for a bucket-mirror config, the importer that fills the
Asset Library. It never runs Workflows itself.
In pipeline terms: a staged job is the T of an ETL flow (no load ever
happens), and an Asset Library job is the T of an ELT flow — the load
already happened, via uploads or a datasource mirror.
Prerequisites
- The workspace needs the batch-processing feature. Gated calls fail with a
402 "Batch processing is not enabled for this workspace. Upgrade your plan
or contact sales at https://roboflow.com/sales."
- Jobs consume credits; the workspace must have a positive balance.
- The Workflow must already exist in the workspace (,
). Jobs reference it by ; there is no
inline-spec option.
- API key: the inference-cli reads from the environment,
and every command also accepts . A key stored by
(
~/.config/roboflow/config.json
) is NOT picked up by
the inference-cli: export it or pass explicitly. Mint one with
the MCP tool. Never have the user paste a private key
into chat.
Where each step runs, and why
Two steps are inference-cli only, because the MCP server can neither read nor
write the user's disk:
- Staging runs on the machine that can reach the files (local disk) or
with the user's cloud credentials (bucket sources).
- Exporting results () downloads into a local directory.
Everything in between needs only an API key, so it works either way: the MCP
tools (
,
batch_processing_staged_job_start
,
,
batch_processing_jobs_list
,
batch_processing_job_logs
,
batch_processing_job_abort
,
batch_processing_job_restart
, plus the
batch_processing_asset_library_*
and
batch_processing_staging_*
families) or the equivalent CLI commands. Prefer the MCP tools when the host has no shell or the user has
no local
; prefer the CLI when the user is already in a
terminal. The full command set for both content types is in sections 1-5.
The
MCP tool routes a request: it settles the batch
id, picks the staging source, and returns the exact ordered commands. It
never touches files or the network, and it does not repeat this document.
The master tool for staged batches:
Prefer
batch_processing_run(batch_id, workflow_id, content_type, ...)
to
drive the flow over a staging batch you name (for Asset Library selections,
use
batch_processing_asset_library_job_create
instead). Each call reads
current state, advances what it can, and returns immediately with a status:
- — no batch yet; the response contains the CLI commands
for the whole run plus cloud-credential guidance. Run them, then call again.
- — files still registering.
- — ingest failed or returned an unknown shard state; no paid
job was started.
- — the job was started or is still working; includes stage progress.
- — includes the export batch id and the first result files with
signed download URLs.
- — includes logs and a restart hint.
The server never waits on your behalf. Non-terminal responses carry
; sleep that long on your side, then call again with the
returned
and the same
to resume. Omit optional creation
settings on a read-only resume: the paid job's stored definition is
authoritative. The server holds no state between calls.
The job is started under an id derived from (workspace, batch, workflow), so
retrying after a lost response re-registers the same job instead of paying for
a second run. (The platform checks credits before that idempotency comparison,
so a retry can still see a 429 first.) A 409 means that id already exists with
different batch/Workflow identity or conflicts with an optional setting you
explicitly supplied. Inspect the job, omit optional settings to monitor it as
stored, or pass a new explicit
for a separate run.
For the advanced knobs (
,
,
,
) use
batch_processing_staged_job_start
directly.
Webhooks
Roboflow will POST job and ingest notifications to a URL you control. There is
no MCP-side relay: pass
to
batch_processing_staged_job_start
, or
on the CLI commands, pointing at your own receiver. The
POST carries an
header with your publishable key.
Caveat: local
video staging does not support
(the CLI
prints a warning and drops it), and a small local
image batch (32 files or
fewer stages as a simple batch) ignores it too. Sharded local image,
cloud-storage and references-file ingests all support it.
If you have no receiver, just poll
(or
, which reports progress on each call).
1. Install the CLI
bash
pip install inference-cli
# For s3:// gs:// az:// sources:
pip install 'inference-cli[cloud-storage]'
Every
command below authenticates via
from the environment, or
on the command itself.
Cloud credentials are picked up from the standard env chains on the machine
running the CLI: AWS via the default credential chain (
honored;
R2/MinIO work via
, with
applied alongside it),
GCS via
GOOGLE_APPLICATION_CREDENTIALS
, Azure via
AZURE_STORAGE_ACCOUNT_NAME
plus
AZURE_STORAGE_ACCOUNT_KEY
or
. For S3/GCS the CLI generates presigned URLs (24h
expiry); for Azure it appends your SAS token, so those URLs stay valid as long
as the token does. Either way the URLs are handed to Roboflow and bucket
secrets never leave the machine.
2. Stage a batch
Batch ids: lowercase letters, digits,
or
. Staged batches expire
after ~7 days.
bash
# Local images (>32 images are packed into tar shards automatically)
inference rf-cloud data-staging create-batch-of-images \
--batch-id my-batch --images-dir ./images
# Local videos (uploaded one by one via signed URLs)
inference rf-cloud data-staging create-batch-of-videos \
--batch-id my-batch --videos-dir ./videos
# Cloud bucket (S3/GCS/Azure; glob over object paths).
# Videos work exactly the same way: create-batch-of-videos.
inference rf-cloud data-staging create-batch-of-images \
--batch-id my-batch --data-source cloud-storage \
--bucket-path 's3://my-bucket/images/**/*.jpg'
inference rf-cloud data-staging create-batch-of-videos \
--batch-id my-batch --data-source cloud-storage \
--bucket-path 's3://my-bucket/videos/**/*.mp4'
# References file: JSONL lines of {"name": ..., "url": "https://..."}
inference rf-cloud data-staging create-batch-of-images \
--batch-id my-batch --data-source references-file --references refs.jsonl
Images vs videos is a choice you make, not something inferred from the path:
and
both accept every data
source. Pick the one matching the content.
Sharded, cloud-storage, and references ingests are asynchronous. Wait until
the batch is fully ingested before starting a job:
bash
inference rf-cloud data-staging show-batch-details --batch-id my-batch
inference rf-cloud data-staging list-ingest-details --batch-id my-batch
or the
batch_processing_staging_batch_get
MCP tool, which returns the file
count plus an
block with
and
flags. Do not start a
job while
is true or
is true: the job costs credits and
would run over incomplete input.
Practical limits: up to 20,000 image references per ingest request
(auto-chunked; video references cap at 5,000 per request and are not chunked),
~1,000 videos per batch suggested, image formats jpg/png/webp/bmp/jp2,
video formats mp4/mov/avi/mkv/flv/wmv/m4v.
batch_processing_staging_batches_list
shows every staged batch in the workspace (inputs and job results).
3. Start the job
CLI, images:
bash
inference rf-cloud batch-processing process-images-with-workflow \
--batch-id my-batch --workflow-id my-workflow --machine-type gpu
CLI, videos:
bash
inference rf-cloud batch-processing process-videos-with-workflow \
--batch-id my-batch --workflow-id my-workflow --machine-type gpu \
--max-video-fps 5
Shared optional flags:
--workers-per-machine 1|2|4|8
,
--aggregation-format jsonl|csv
,
,
--image-outputs-to-save <name>
,
--image-input-name <name>
,
--workflow-params params.json
,
--max-runtime-seconds <n>
,
,
,
,
--notifications-url <url>
,
.
Images only:
--max-image-failure-rate 0.0-1.0
(the server rejects it on
video jobs). Videos only:
.
MCP equivalent:
batch_processing_staged_job_start(
job_id="my-stable-job-id", # required; reuse for retries
batch_id="my-batch", workflow_id="my-workflow",
content_type="images", # or "videos"
machine_type="gpu", # cpu|gpu, optional
workers_per_machine=4, # 1, 2, 4 or 8, optional
aggregation_format="jsonl", # or "csv"
save_image_outputs=True, # persist crops/visualizations
)
For videos, set
and optionally
(prediction subsampling). The tool rejects
on image jobs and
on video jobs, matching the platform.
Choosing cpu vs gpu ()
Default compute is CPU. Decide with two quick checks before starting a paid
job over the whole batch:
- Test-run the Workflow on one representative image ( MCP
tool, or the hosted API) and measure the wall time. Run it twice and time
the second call (the first may cold-start). If a single image takes more
than about a second of model time, CPU workers will crawl through a large
batch: take .
- Inspect the Workflow spec (): count the model steps and
note their sizes. One small fine-tuned detector/classifier: is the
cheapest and usually enough. Several models chained, or any large
foundation model (SAM family, CLIP, OCR, VLM blocks): .
Videos multiply per-frame work with
, so lean
there
too.
(1/2/4/8) then scales throughput on one machine:
more workers means better utilization but a higher OOM risk.
Same job_id plus an identical definition is idempotent; a divergent one is
rejected with a 409. The tool checks that ingest is complete before the paid
registration call. For a multipart input, pass
; it is also
supported by
. Both tools default to the current
backend; use
inference_backend="old-inference"
only for a
known compatibility requirement.
4. Monitor
bash
inference rf-cloud batch-processing show-job-details --job-id my-job
inference rf-cloud batch-processing fetch-logs --job-id my-job
inference rf-cloud batch-processing abort-job --job-id my-job
inference rf-cloud batch-processing restart-job --job-id my-job
MCP equivalents, which return JSON rather than a rendered table:
batch_processing_job_get(job_id)
— status, current/planned stages,
per-stage progress, output batches; + are the
end states.
batch_processing_job_logs(job_id)
— info/error logs for diagnosis.
batch_processing_job_abort(job_id)
/ batch_processing_job_restart(job_id)
— stop a run, or retry a failed one (optionally overriding machine type,
workers, timeout).
batch_processing_jobs_list(search=...)
— the workspace's recent Workflow
jobs, for finding a job id you did not keep. Internal TensorRT compilation
jobs are excluded. Both this tool and label each
job with : (platform-staged selection) or
(a batch you staged yourself).
5. Download results
Results land in Data Staging as platform-generated batches:
(raw per-shard outputs) and
(packaged, downloadable archives).
Downloading writes to disk, so this step is CLI only:
bash
inference rf-cloud data-staging export-batch \
--batch-id my-job-export --target-dir ./results
It is resumable; add
to re-pull content already
exported, and
to fetch one part of a multipart batch.
The MCP tool
batch_processing_staging_batch_files_list(batch_id="<job-id>-export")
lists the same files with signed
s (~24h expiry) so a host with no
shell can still fetch them. Export batches are multipart: the tool selects the
part automatically when there is exactly one, and otherwise asks you to pass
(the parts are in
batch_processing_staging_batch_get
). Archives
(
/
) must be unpacked after download, and listings are capped
at 10,000 entries per call — past that scale keep paginating with
and per-part
listings, or pull everything with the
resumable
.
Do this within 7 days: staged inputs and results expire.