Tools

Batch Run

batch_run MCP

Run any other tool over many records, from a list, a SQL query, a table or an uploaded CSV, and collect the results in a file or a table.

Run one tool over many records at once. This is the only way to fan a tool out: every other tool takes exactly one item. Sources: `rows` (records in the call itself), `sql` (a BigQuery query), `table` (a whole catalog table), `file` (a CSV/TSV uploaded at https://app.botify.com/:organization/:project/o/storage/tmp, or the output of a previous batch). Small sources run immediately and return their results. Larger ones run as a background job: you get a job_id to poll with batch_status, and the records never enter this conversation. The output is a temporary JSONL file whose URL is directly usable as the `file` source of a next batch, which is how several tools are chained. Each line is {row, item, response, error} -- the original row and mapped item are both kept, so results stay attributable and source columns survive chaining. Use tool_documentation on the target tool first: item_map has to match its item schema. Use dry_run to check a mapping against real records before paying for the whole source.

Playground

Your organization, project and token stay in this browser's local storage and are sent straight to the API — this page never sees them.

Organization Project API token

POST

item

tool required Id of the tool to run over every record. Use tool_documentation to read its item schema before writing item_map.

source required Where the records come from.

item_map Projection from a source record onto the tool's item, using {{row.<column>}} (ex: {"url": "{{row.page_url}}"}). Omit it when the records already have the tool's item shape.

sink Where results go. Defaults to a temporary gzipped JSONL file whose URL can be passed straight back as a file source.

tool_config The target tool's own config, shared by every record.

dry_run Run only the first 5 records and return them in full, launching nothing. Use it to check a mapping or a prompt against a large source in one turn.

config

on_error skip: record the failure and carry on. fail_job: stop the whole batch on the first failing record.

chunk_size Records sent to the tool at once.

inline_max_rows Above this many records, the batch runs as a job.

Billing

These usage SKUs can be charged on a call.

SKU	Credits	Description
Tool call	1 per request	Charged once per successful item.

Schemas

item is what you send, config how the tool behaves, and the response is what you get back.

Item

object

Properties

tool string required

Id of the tool to run over every record. Use tool_documentation to read its item schema before writing item_map.

source SourceSpec required

Where the records come from.

Type: SourceSpec

item_map object | null

Projection from a source record onto the tool's item, using {{row.<column>}} (ex: {"url": "{{row.page_url}}"}). Omit it when the records already have the tool's item shape.

Default: null

sink SinkSpec

Where results go. Defaults to a temporary gzipped JSONL file whose URL can be passed straight back as a file source.

Type: SinkSpec

Default: null

tool_config object | null

The target tool's own config, shared by every record.

Default: null

dry_run boolean

Run only the first 5 records and return them in full, launching nothing. Use it to check a mapping or a prompt against a large source in one turn.

Default: false

Example

{
  "tool": "string",
  "source": {
    "type": "rows",
    "rows": [
      {}
    ]
  },
  "item_map": null,
  "sink": null,
  "tool_config": null,
  "dry_run": false
}

Type Definitions

9 types

These are the available sub-object types that can be used in the properties above.

FileFormat string

Values: auto jsonl csv tsv

FileSink object

A temporary JSONL file in project storage, readable back as a source.

type string

Default: "file"

gzip boolean

Compress the output.

Default: true

FileSource object

Rows from an uploaded CSV/TSV, or from a previous batch's JSONL output.

type string

Default: "file"

url string required

File URL. Upload a local file at https://app.botify.com/:organization/:project/o/storage/tmp and pass the returned URL, or reuse the sink URL of a previous batch. Public HTTP(S) URLs are accepted too. CSV, TSV and JSONL, gzip allowed.

format FileFormat

File format, or auto-detect.

Type: FileFormat

Default: "auto"

RowsSource object

Records passed directly in the call.

type string

Default: "rows"

rows array required

The records to process, one object per call.

min items 1

SinkSpec

Type: FileSink | TableSink

Discriminated by type (2 variants)

SourceSpec

Type: RowsSource | SqlSource | TableSource | FileSource

Discriminated by type (4 variants)

SqlSource object

Rows from a BigQuery query over the project's catalog.

type string

Default: "sql"

query string required

BigQuery Standard SQL over catalog tables. Prefix every table with "catalog." (ex: catalog.crawl_pages_20251201). Same access as tables_query.

limit integer | null

Stop after this many rows.

Default: null

TableSink object

A table in the project's editable catalog.

type string

Default: "table"

table string required

Destination table in the catalog.

pattern "^[A-Za-z_][A-Za-z0-9_]{0,1023}$"

row_map object | null

Column projection, using {{item.<field>}}, {{response.<field>}}, {{error}} and {{row.<column>}}. Defaults to `row`, `item`, `response` and `error` columns.

Default: null

replace_existing boolean

Replace the table instead of appending to it.

Default: false

TableSource object

Every row of one catalog table.

type string

Default: "table"

table string required

Table name, with or without the "catalog." prefix.

pattern "^(?:catalog\\.)?[A-Za-z_][A-Za-z0-9_]*$"

limit integer | null

Stop after this many rows.

Default: null

Configuration

object

Properties

on_error OnError

skip: record the failure and carry on. fail_job: stop the whole batch on the first failing record.

Type: OnError

Default: "skip"

chunk_size integer

Records sent to the tool at once.

Default: 50

min 1, max 500

inline_max_rows integer

Above this many records, the batch runs as a job.

Default: 10

min 1, max 100

Example

{
  "on_error": "skip",
  "chunk_size": 50,
  "inline_max_rows": 10
}

Type Definitions

1 type

These are the available sub-object types that can be used in the properties above.

OnError string

Values: skip fail_job

Response

object

What a batch returns, whichever path it took.

Properties

mode string required

dry_run and inline carry their results; job carries a job_id to poll with batch_status.

Values: dry_run inline job

tool string required

The tool that was run.

results array | null

One {item, response, error} object per record.

Default: null

job_id string | null

Poll it with batch_status.

Default: null

execution_id string | null

Underlying Cloud Run execution.

Default: null

rows_total integer | null

Records the batch will process.

Default: null

rows_ok integer | null

Records that succeeded.

Default: null

rows_error integer | null

Records that failed.

Default: null

estimated_credits integer | null

Credits the batch is expected to cost.

Default: null

sink SinkPointer

Where the output landed.

Type: SinkPointer

Default: null

message string | null

One line about the outcome.

Default: null

Example

{
  "mode": "dry_run",
  "tool": "string",
  "results": null,
  "job_id": null,
  "execution_id": null,
  "rows_total": null,
  "rows_ok": null,
  "rows_error": null,
  "estimated_credits": null,
  "sink": null,
  "message": null
}

Type Definitions

1 type

These are the available sub-object types that can be used in the properties above.

SinkPointer object

Where a batch's output landed.

type string required

Values: file table

url string | null

Sink file URL, reusable as the source of a next batch.

Default: null

table string | null

Destination table.

Default: null

rows_written integer

Records written.

Default: 0

Endpoints

POST http://agents.botify.com/{organization}/{project}/batch_run/process

POST http://agents.botify.com/{organization}/{project}/batch_run/batch_process

POST http://agents.botify.com/{organization}/{project}/batch_run/async_process

POST http://agents.botify.com/{organization}/{project}/batch_run/async_batch_process

See running a long job in the background for the polling flow.

cURL

curl -X POST "http://agents.botify.com/{organization}/{project}/batch_run/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {
    "tool": "<tool>",
    "source": "<source>"
  }
}'

Over MCP

This tool is exposed as the MCP tool batch_run. An MCP client passes organization, project and item as tool arguments. Set up MCP →

Raw metadata

GET /agents/batch_run — this page as JSON.
/agents/batch_run/skill.md — Markdown for coding agents.