Use the Batch API to execute a published Function over production data. The
Function supplies its optimized prompt, model, output schema, and runtime
defaults. You may also call an available model ID directly when you do not need
a Function.Configure your deployment URL and API key before
using the examples below.
Use the deployment where you published the Function.
Headers
string
required
Deployment API key in the form Key YOUR_SUTRO_API_KEY.
Body
string[] | object[] | string
required
Function input objects, already-rendered strings, or an HTTPS CSV/Parquet/JSONL download URL. Object keys or remote columns must match the Function inputs. Direct text model calls use strings; native vision models also accept typed media rows. s3:// URIs are not accepted by this HTTP endpoint; the SDK signs them before submission.
string
default:"gemma-4-26b-a4b-it"
The published Function name. Sutro resolves it within the API key owner’s account to the currently published revision. An available model ID may be supplied instead to run that model directly.
string | null
default:"null"
Input column for a standalone-model URL. Defaults to the first column. Omit for Functions.
string | null
default:"null"
Remote-input column to preserve in every result format. It must exist, differ from inference columns, and not use SKYSIGHT_, inputs, outputs, confidence_score, or cumulative_logprobs.
string | null
default:"null"
System prompt for a standalone model. Functions use their published prompt.
object | null
default:"null"
JSON Schema for standalone-model structured output. Functions use their published schema.
object | null
default:"null"
Generation settings. For Functions, request values override published runtime defaults.
Create an estimate job instead of a full job. After it succeeds, read cost_estimate from the job record. See Production Batch.
boolean
default:"false"
Generate a random seed for each row.
boolean
default:"true"
Trim oversized text rows to the model context window. If false, an oversized row fails the job. Native media rows exceeding page or model-context limits are always rejected rather than truncated.
string | null
default:"null"
Optional job name, up to 45 characters.
string | null
default:"null"
Optional description, up to 512 characters.
Batch supports typed image and PDF Functions when the selected native model
and deployment support those inputs. Native PDF support is available for
Qwen3.5 and Gemma 4 vision models. Asset fields accept HTTPS URLs, inline asset
objects, or names already uploaded to the Function’s asset collection. Remote
CSV asset columns can use HTTPS URLs or those stored names.Deployment operators must roll out the native sidecar and Batch GPU workers
together before advertising native PDF support.Native Batch ingestion accepts PNG, JPEG, and WebP images up to 20 MiB each
through HTTPS URLs or raw image data URI strings, including HTTPS URLs in
remote CSV columns. Image uploads through the SDK or Harmonize, and images in
dataset or Function collections, are limited to 5 MiB each, including review
reimports. Use HTTPS URLs for Batch images larger than 5 MiB.Unencrypted PDFs are limited to 32 MiB each. PDFs are rendered on the server
into page images with extracted text and page numbers, using the same representation as real-time
Functions. The limit is eight images total per row, counting each PDF page and
each separate image. Inputs exceeding that limit or the model’s context
window are rejected rather than truncated. Asset bytes are retained during
admission for inference and review. The
Python SDK uploads
inline images and PDFs once per content digest.Encrypted PDFs and XFA forms are unsupported; export XFA forms to standard PDFs
first. Documents exceeding preprocessing resource limits, including one million
extracted characters per PDF, are rejected without truncation.
Batch does not execute Function web search or tool calls.
string | null
default:"null"
Optional client-generated UUID for retry-safe S3 submission. Provide it together with input_source, persist it before sending, and reuse it when replaying the same logical request. Without it, ambiguous retries can create duplicate jobs.
object | null
default:"null"
Pinned S3 identity, provided together with idempotency_key: bucket, key, etag, size_bytes, and optional version_id. inputs must be a signed HTTPS GET URL for that same object and version.
For image and PDF Functions, refreshed asset receipts must identify the same
authenticated owner, asset content, and field bindings. Renewing receipt tokens
does not change the logical submission; changing an asset or its binding
requires a new key. The upload endpoint and request catalog retain their
existing image-assets and image_assets names for both images and PDFs.For ordinary URL input, use a sufficiently long-lived presigned HTTPS GET URL.
Each ingestion attempt performs a full-object download; the transfer does not
resume. Only public destinations on standard HTTP(S) ports are supported, and
downloads never use service credentials. See
remote-input limits.
Set column_name explicitly for standalone models; for Functions, omit it and
provide columns matching the Function inputs. Null Function values become
empty strings, and extra fields are ignored. For recoverable ingestion and
safe replay, use the S3 submission protocol below.
For generation without a published Function, set model to an available model
ID and provide rendered string inputs. In this mode you may set
system_prompt, json_schema, and sampling_params directly.
results and metadata.job_id are the same job ID. Monitor it with
job status. Requests without idempotency_key
are not idempotent: retrying after an uncertain response can create duplicate
work, and execution validation can still fail after acceptance.
Retry-safe S3 submission
For the full client workflow, use
batch_run_function()
or the CLI. Custom API
clients must first check
deployment capabilities,
then persist a UUID before the first POST. Keep request fields and source
identity unchanged when retrying. The signed GET URL may be refreshed using
local AWS credentials for the same pinned object.
Use metadata from S3 to populate input_source; omit version_id when the
object is unversioned. The deployment retains and validates that exact object
before accepting work. The first resolved Function configuration is retained
across ingestion retries. Never log signed URLs or include them in receipts.While ingestion runs, POST returns HTTP 202:
Read GET /v1/batch-submissions/{idempotency_key}
to recover its state after a lost response. Acceptance returns HTTP 200 with
status: "ACCEPTED" and the original job ID. Replaying an accepted request
returns that same job. A changed logical request with the same key returns
409; terminal input failure returns 422, and retryable ingestion failure
may return 503. Check the reservation before replaying an uncertain POST;
network errors are not a reason to generate a new key.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Sutro Docs","colors":{"primary":"#2457DC","light":"#2457DC","dark":"#AAB3F3"},"logo":{"light":"https://mintcdn.com/sutro-d5dc9f29/2FChvrRfipPLBgk-/Logo/sutro-light.svg?fit=max\u0026auto=format\u0026n=2FChvrRfipPLBgk-\u0026q=85\u0026s=d97c22cc3edd64b9889c1397a07aa548","dark":"https://mintcdn.com/sutro-d5dc9f29/2FChvrRfipPLBgk-/Logo/sutro-dark.svg?fit=max\u0026auto=format\u0026n=2FChvrRfipPLBgk-\u0026q=85\u0026s=b71ebe7b47e61f8955a12bdbc478f6b0","href":"https://sutro.sh/"},"navbar":{"links":[{"href":"/reference/authentication","label":"Connect your deployment"}],"primary":{"type":"button","label":"Try Sutro","href":"https://cal.com/team/sutro/demo"}},"footer":{},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"sutro-d5dc9f29","hasAudioNarration":false,"actualSubdomain":"sutro-d5dc9f29","customDomains":["docs.sutro.sh"],"gitSource":{"type":"github","owner":"sutro-sh","repo":"foundation","deployBranch":"main","contentDirectory":"docs","isPrivate":true,"mountPath":"","label":""},"entitlements":{},"buildId":"6afe5730111c5baa897d2640","clientVersion":"0.0.4205","searchFilterCounts":[{"language":"default","tag":"Reference","count":22},{"language":"default","tag":"API","count":11},{"language":"default","tag":"Python SDK","count":7},{"language":"default","tag":"Functions","count":3},{"language":"default","tag":"Product","count":3},{"language":"default","tag":"Batch","count":2},{"language":"default","tag":"Start","count":2},{"language":"default","tag":"MCP","count":1}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"reference/api/running-batch-inference","slug":"/reference/api/running-batch-inference","pageMetadata":{"title":"Run a Function in Batch","api":"POST https://your-sutro-deployment.example.com/v1/batch-inference","description":"Execute a published Function asynchronously over inline or remote inputs.","href":"/reference/api/running-batch-inference"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Execute a published Function asynchronously over inline or remote inputs.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,..._provideComponents(),...props.components},{CodeBlock,Heading,ParamField,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!ParamField)_missingMdxReference(`ParamField`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Use the Batch API to execute a published Function over production data. The\nFunction supplies its optimized prompt, model, output schema, and runtime\ndefaults. You may also call an available model ID directly when you do not need\na Function.`}),`\n`,_jsxs(_components.p,{children:[`Configure your `,_jsx(_components.a,{href:`/reference/authentication`,children:`deployment URL and API key`}),` before\nusing the examples below.\nUse the deployment where you published the Function.`]}),`\n`,_jsx(Heading,{level:`2`,id:`headers`,children:`Headers`}),`\n`,_jsx(ParamField,{header:`Authorization`,type:`string`,required:true,id:`param-authorization`,children:_jsxs(_components.p,{children:[`Deployment API key in the form `,_jsx(_components.code,{children:`Key YOUR_SUTRO_API_KEY`}),`.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`body`,children:`Body`}),`\n`,_jsx(ParamField,{body:`inputs`,type:`string[] | object[] | string`,required:true,id:`param-inputs`,children:_jsxs(_components.p,{children:[`Function input objects, already-rendered strings, or an HTTPS CSV/Parquet/JSONL download URL. Object keys or remote columns must match the Function inputs. Direct text model calls use strings; native vision models also accept typed media rows. `,_jsx(_components.code,{children:`s3://`}),` URIs are not accepted by this HTTP endpoint; the SDK signs them before submission.`]})}),`\n`,_jsx(ParamField,{body:`model`,type:`string`,default:`gemma-4-26b-a4b-it`,id:`param-model`,children:_jsx(_components.p,{children:`The published Function name. Sutro resolves it within the API key owner’s account to the currently published revision. An available model ID may be supplied instead to run that model directly.`})}),`\n`,_jsx(ParamField,{body:`column_name`,type:`string | null`,default:`null`,id:`param-column-name`,children:_jsx(_components.p,{children:`Input column for a standalone-model URL. Defaults to the first column. Omit for Functions.`})}),`\n`,_jsx(ParamField,{body:`id_column_name`,type:`string | null`,default:`null`,id:`param-id-column-name`,children:_jsxs(_components.p,{children:[`Remote-input column to preserve in every result format. It must exist, differ from inference columns, and not use `,_jsx(_components.code,{children:`SKYSIGHT_`}),`, `,_jsx(_components.code,{children:`inputs`}),`, `,_jsx(_components.code,{children:`outputs`}),`, `,_jsx(_components.code,{children:`confidence_score`}),`, or `,_jsx(_components.code,{children:`cumulative_logprobs`}),`.`]})}),`\n`,_jsx(ParamField,{body:`system_prompt`,type:`string | null`,default:`null`,id:`param-system-prompt`,children:_jsx(_components.p,{children:`System prompt for a standalone model. Functions use their published prompt.`})}),`\n`,_jsx(ParamField,{body:`json_schema`,type:`object | null`,default:`null`,id:`param-json-schema`,children:_jsx(_components.p,{children:`JSON Schema for standalone-model structured output. Functions use their published schema.`})}),`\n`,_jsx(ParamField,{body:`sampling_params`,type:`object | null`,default:`null`,id:`param-sampling-params`,children:_jsx(_components.p,{children:`Generation settings. For Functions, request values override published runtime defaults.`})}),`\n`,_jsx(ParamField,{body:`job_priority`,type:`integer`,default:`0`,id:`param-job-priority`,children:_jsxs(_components.p,{children:[_jsx(_components.code,{children:`0`}),` for prototyping or `,_jsx(_components.code,{children:`1`}),` for the `,_jsx(_components.a,{href:`/batch/run-model#job-priority-and-sla`,children:`one-hour production SLA`}),`.`]})}),`\n`,_jsx(ParamField,{body:`cost_estimate`,type:`boolean`,default:`false`,id:`param-cost-estimate`,children:_jsxs(_components.p,{children:[`Create an estimate job instead of a full job. After it succeeds, read `,_jsx(_components.code,{children:`cost_estimate`}),` from the job record. See `,_jsx(_components.a,{href:`/batch/production`,children:`Production Batch`}),`.`]})}),`\n`,_jsx(ParamField,{body:`random_seed_per_input`,type:`boolean`,default:`false`,id:`param-random-seed-per-input`,children:_jsx(_components.p,{children:`Generate a random seed for each row.`})}),`\n`,_jsx(ParamField,{body:`truncate_rows`,type:`boolean`,default:`true`,id:`param-truncate-rows`,children:_jsxs(_components.p,{children:[`Trim oversized text rows to the model context window. If `,_jsx(_components.code,{children:`false`}),`, an oversized row fails the job. Native media rows exceeding page or model-context limits are always rejected rather than truncated.`]})}),`\n`,_jsx(ParamField,{body:`name`,type:`string | null`,default:`null`,id:`param-name`,children:_jsx(_components.p,{children:`Optional job name, up to 45 characters.`})}),`\n`,_jsx(ParamField,{body:`description`,type:`string | null`,default:`null`,id:`param-description`,children:_jsx(_components.p,{children:`Optional description, up to 512 characters.`})}),`\n`,_jsx(_components.p,{children:`Batch supports typed image and PDF Functions when the selected native model\nand deployment support those inputs. Native PDF support is available for\nQwen3.5 and Gemma 4 vision models. Asset fields accept HTTPS URLs, inline asset\nobjects, or names already uploaded to the Function’s asset collection. Remote\nCSV asset columns can use HTTPS URLs or those stored names.`}),`\n`,_jsx(_components.p,{children:`Deployment operators must roll out the native sidecar and Batch GPU workers\ntogether before advertising native PDF support.`}),`\n`,_jsx(_components.p,{children:`Native Batch ingestion accepts PNG, JPEG, and WebP images up to 20 MiB each\nthrough HTTPS URLs or raw image data URI strings, including HTTPS URLs in\nremote CSV columns. Image uploads through the SDK or Harmonize, and images in\ndataset or Function collections, are limited to 5 MiB each, including review\nreimports. Use HTTPS URLs for Batch images larger than 5 MiB.`}),`\n`,_jsxs(_components.p,{children:[`Unencrypted PDFs are limited to 32 MiB each. PDFs are rendered on the server\ninto page images with extracted text and page numbers, using the same representation as real-time\nFunctions. The limit is eight images total per row, counting each PDF page and\neach separate image. Inputs exceeding that limit or the model’s context\nwindow are rejected rather than truncated. Asset bytes are retained during\nadmission for inference and review. The\n`,_jsx(_components.a,{href:`/reference/python-sdk/functions#image-and-pdf-inputs`,children:`Python SDK`}),` uploads\ninline images and PDFs once per content digest.`]}),`\n`,_jsx(_components.p,{children:`Encrypted PDFs and XFA forms are unsupported; export XFA forms to standard PDFs\nfirst. Documents exceeding preprocessing resource limits, including one million\nextracted characters per PDF, are rejected without truncation.`}),`\n`,_jsx(Warning,{children:`Batch does not execute Function web search or tool calls.`}),`\n`,_jsx(ParamField,{body:`idempotency_key`,type:`string | null`,default:`null`,id:`param-idempotency-key`,children:_jsxs(_components.p,{children:[`Optional client-generated UUID for retry-safe S3 submission. Provide it together with `,_jsx(_components.code,{children:`input_source`}),`, persist it before sending, and reuse it when replaying the same logical request. Without it, ambiguous retries can create duplicate jobs.`]})}),`\n`,_jsx(ParamField,{body:`input_source`,type:`object | null`,default:`null`,id:`param-input-source`,children:_jsxs(_components.p,{children:[`Pinned S3 identity, provided together with `,_jsx(_components.code,{children:`idempotency_key`}),`: `,_jsx(_components.code,{children:`bucket`}),`, `,_jsx(_components.code,{children:`key`}),`, `,_jsx(_components.code,{children:`etag`}),`, `,_jsx(_components.code,{children:`size_bytes`}),`, and optional `,_jsx(_components.code,{children:`version_id`}),`. `,_jsx(_components.code,{children:`inputs`}),` must be a signed HTTPS GET URL for that same object and version.`]})}),`\n`,_jsxs(_components.p,{children:[`For image and PDF Functions, refreshed asset receipts must identify the same\nauthenticated owner, asset content, and field bindings. Renewing receipt tokens\ndoes not change the logical submission; changing an asset or its binding\nrequires a new key. The upload endpoint and request catalog retain their\nexisting `,_jsx(_components.code,{children:`image-assets`}),` and `,_jsx(_components.code,{children:`image_assets`}),` names for both images and PDFs.`]}),`\n`,_jsxs(_components.p,{children:[`For ordinary URL input, use a sufficiently long-lived presigned HTTPS GET URL.\nEach ingestion attempt performs a full-object download; the transfer does not\nresume. Only public destinations on standard HTTP(S) ports are supported, and\ndownloads never use service credentials. See\n`,_jsx(_components.a,{href:`/reference/python-sdk/presigned-s3-inputs#contract`,children:`remote-input limits`}),`.\nSet `,_jsx(_components.code,{children:`column_name`}),` explicitly for standalone models; for Functions, omit it and\nprovide columns matching the Function inputs. Null Function values become\nempty strings, and extra fields are ignored. For recoverable ingestion and\nsafe replay, use the S3 submission protocol below.`]}),`\n`,_jsx(Heading,{level:`2`,id:`run-a-published-function`,children:`Run a published Function`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`8`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --fail-with-body`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`SUTRO_API_URL`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`%/`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}/v1/batch-inference\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Key `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`$SUTRO_API_KEY`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Content-Type: application/json\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '{`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"model\": \"lead-qualifier\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"inputs\": [{\"query\": \"Find security leaders\", \"region\": \"EMEA\"}],`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"name\": \"lead-smoke\"`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` }'`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`call-a-model-id-directly`,children:`Call a model ID directly`}),`\n`,_jsxs(_components.p,{children:[`For generation without a published Function, set `,_jsx(_components.code,{children:`model`}),` to an available model\nID and provide rendered string inputs. In this mode you may set\n`,_jsx(_components.code,{children:`system_prompt`}),`, `,_jsx(_components.code,{children:`json_schema`}),`, and `,_jsx(_components.code,{children:`sampling_params`}),` directly.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`9`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`9`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --fail-with-body`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:' \"${'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`SUTRO_API_URL`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`%/`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`}/v1/batch-inference\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Key `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`$SUTRO_API_KEY`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Content-Type: application/json\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '{`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"model\": \"gemma-4-26b-a4b-it\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"inputs\": [\"Summarize this report.\", \"Classify this request.\"],`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"system_prompt\": \"Answer concisely.\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"job_priority\": 0`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` }'`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`response`,children:`Response`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`7`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`7`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"metadata\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"job_id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"job-12345678-1234-1234-1234-1234567890ab\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"message\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Job created successfully\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"results\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"job-12345678-1234-1234-1234-1234567890ab\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`results`}),` and `,_jsx(_components.code,{children:`metadata.job_id`}),` are the same job ID. Monitor it with\n`,_jsx(_components.a,{href:`/reference/api/job-status`,children:`job status`}),`. Requests without `,_jsx(_components.code,{children:`idempotency_key`}),`\nare not idempotent: retrying after an uncertain response can create duplicate\nwork, and execution validation can still fail after acceptance.`]}),`\n`,_jsx(Heading,{level:`2`,id:`retry-safe-s3-submission`,children:`Retry-safe S3 submission`}),`\n`,_jsxs(_components.p,{children:[`For the full client workflow, use\n`,_jsx(_components.a,{href:`/reference/python-sdk/functions#retry-safe-s3-submission`,children:_jsx(_components.code,{children:`batch_run_function()`})}),`\nor the `,_jsx(_components.a,{href:`/reference/cli/index#resumable-s3-batches`,children:`CLI`}),`. Custom API\nclients must first check\n`,_jsx(_components.a,{href:`/reference/api/batch-submissions#check-deployment-capabilities`,children:`deployment capabilities`}),`,\nthen persist a UUID before the first POST. Keep request fields and source\nidentity unchanged when retrying. The signed GET URL may be refreshed using\nlocal AWS credentials for the same pinned object.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`14`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`14`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"model\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"lead-qualifier\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"inputs\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"https://my-bucket.s3.us-east-2.amazonaws.com/input.jsonl?SIGNED_QUERY\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"job_priority\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`1`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"truncate_rows\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`false`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"idempotency_key\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"889b580e-90ee-4c47-9949-1ae63c6dcb76\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"input_source\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"bucket\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"my-bucket\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"key\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"input.jsonl\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"etag\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:`\\\\\"`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`object-etag`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:`\\\\\"`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"size_bytes\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`123`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"version_id\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"object-version\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Use metadata from S3 to populate `,_jsx(_components.code,{children:`input_source`}),`; omit `,_jsx(_components.code,{children:`version_id`}),` when the\nobject is unversioned. The deployment retains and validates that exact object\nbefore accepting work. The first resolved Function configuration is retained\nacross ingestion retries. Never log signed URLs or include them in receipts.`]}),`\n`,_jsxs(_components.p,{children:[`While ingestion runs, POST returns HTTP `,_jsx(_components.code,{children:`202`}),`:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`5`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"status\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"INGESTING\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"idempotency_key\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"889b580e-90ee-4c47-9949-1ae63c6dcb76\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"retryable\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`false`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Read `,_jsx(_components.a,{href:`/reference/api/batch-submissions`,children:_jsx(_components.code,{children:`GET /v1/batch-submissions/{idempotency_key}`})}),`\nto recover its state after a lost response. Acceptance returns HTTP `,_jsx(_components.code,{children:`200`}),` with\n`,_jsx(_components.code,{children:`status: \"ACCEPTED\"`}),` and the original job ID. Replaying an accepted request\nreturns that same job. A changed logical request with the same key returns\n`,_jsx(_components.code,{children:`409`}),`; terminal input failure returns `,_jsx(_components.code,{children:`422`}),`, and retryable ingestion failure\nmay return `,_jsx(_components.code,{children:`503`}),`. Check the reservation before replaying an uncertain POST;\nnetwork errors are not a reason to generate a new key.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Run a Function in Batch","api":"POST https://your-sutro-deployment.example.com/v1/batch-inference","description":"Execute a published Function asynchronously over inline or remote inputs.","href":"/reference/api/running-batch-inference"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Headers","slug":"headers","depth":2,"children":[]},{"title":"Body","slug":"body","depth":2,"children":[]},{"title":"Run a published Function","slug":"run-a-published-function","depth":2,"children":[]},{"title":"Call a model ID directly","slug":"call-a-model-id-directly","depth":2,"children":[]},{"title":"Response","slug":"response","depth":2,"children":[]},{"title":"Retry-safe S3 submission","slug":"retry-safe-s3-submission","depth":2,"children":[]}],"codeExamples":{},"endpoint":{"title":"Run a Function in Batch","path":"/v1/batch-inference","servers":[{"url":"https://your-sutro-deployment.example.com"}],"method":"post","request":{"security":[],"parameters":{"query":{},"header":{"Authorization":{"schema":[{"type":"string","description":"Deployment API key in the form `Key YOUR_SUTRO_API_KEY` .","required":true}]}},"cookie":{},"path":{}},"body":{"application/json":{"schemaArray":[{"type":"object","properties":{"inputs":[{"type":"object","properties":{},"description":"Function input objects, already-rendered strings, or an HTTPS CSV/Parquet/JSONL download URL. Object keys or remote columns must match the Function inputs. Direct text model calls use strings; native vision models also accept typed media rows. `s3://` URIs are not accepted by this HTTP endpoint; the SDK signs them before submission.","required":true}],"model":[{"type":"string","description":"The published Function name. Sutro resolves it within the API key owner’s account to the currently published revision. An available model ID may be supplied instead to run that model directly."}],"column_name":[{"type":"object","properties":{},"description":"Input column for a standalone-model URL. Defaults to the first column. Omit for Functions."}],"id_column_name":[{"type":"object","properties":{},"description":"Remote-input column to preserve in every result format. It must exist, differ from inference columns, and not use `SKYSIGHT_` , `inputs` , `outputs` , `confidence_score` , or `cumulative_logprobs` ."}],"system_prompt":[{"type":"object","properties":{},"description":"System prompt for a standalone model. Functions use their published prompt."}],"json_schema":[{"type":"object","properties":{},"description":"JSON Schema for standalone-model structured output. Functions use their published schema."}],"sampling_params":[{"type":"object","properties":{},"description":"Generation settings. For Functions, request values override published runtime defaults."}],"job_priority":[{"type":"integer","description":"`0` for prototyping or `1` for the one-hour production SLA ."}],"cost_estimate":[{"type":"boolean","description":"Create an estimate job instead of a full job. After it succeeds, read `cost_estimate` from the job record. See Production Batch ."}],"random_seed_per_input":[{"type":"boolean","description":"Generate a random seed for each row."}],"truncate_rows":[{"type":"boolean","description":"Trim oversized text rows to the model context window. If `false` , an oversized row fails the job. Native media rows exceeding page or model-context limits are always rejected rather than truncated."}],"name":[{"type":"object","properties":{},"description":"Optional job name, up to 45 characters."}],"description":[{"type":"object","properties":{},"description":"Optional description, up to 512 characters."}],"idempotency_key":[{"type":"object","properties":{},"description":"Optional client-generated UUID for retry-safe S3 submission. Provide it together with `input_source` , persist it before sending, and reuse it when replaying the same logical request. Without it, ambiguous retries can create duplicate jobs."}],"input_source":[{"type":"object","properties":{},"description":"Pinned S3 identity, provided together with `idempotency_key` : `bucket` , `key` , `etag` , `size_bytes` , and optional `version_id` . `inputs` must be a signed HTTPS GET URL for that same object and version."}]}}],"examples":{"example":{"value":{"inputs":{},"model":"\u003cstring>","column_name":{},"id_column_name":{},"system_prompt":{},"json_schema":{},"sampling_params":{},"job_priority":123,"cost_estimate":true,"random_seed_per_input":true,"truncate_rows":true,"name":{},"description":{},"idempotency_key":{},"input_source":{}}}}}}},"response":{},"deprecated":false}},"jsLinks":["/_mintlify/custom/sutro-d5dc9f29/226d2858a53bad9f/site-observability.js"],"subdomain":"sutro-d5dc9f29","siteName":"Sutro Docs","title":"Run a Function in Batch - Sutro Docs","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-16T20:46:32.293Z","originalFileLocation":"reference/api/running-batch-inference.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Execute a published Function asynchronously over inline or remote inputs.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Sutro Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/sutro-d5dc9f29/_generated/favicon/apple-touch-icon.png?v=3\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/sutro-d5dc9f29/_generated/favicon/favicon-32x32.png?v=3\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/sutro-d5dc9f29/_generated/favicon/favicon-16x16.png?v=3\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/sutro-d5dc9f29/_generated/favicon/favicon.ico?v=3\">\u003cmeta data-mint-head property=\"og:title\" content=\"Run a Function in Batch - Sutro Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Execute a published Function asynchronously over inline or remote inputs.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Sutro Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.sutro.sh/reference/api/running-batch-inference\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://sutro-d5dc9f29.mintlify.site/_mintlify/api/og/v2?division=API\u0026amp;title=Run+a+Function+in+Batch\u0026amp;description=Execute+a+published+Function+asynchronously+over+inline+or+remote+inputs.\u0026amp;theme=f9722fee9e8f402d13bdb22b\u0026amp;signature=9e313e6a15763d76180183273210767061ce129bc1cf87a086721d1b15bde02a\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Run a Function in Batch - Sutro Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Execute a published Function asynchronously over inline or remote inputs.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://sutro-d5dc9f29.mintlify.site/_mintlify/api/og/v2?division=API\u0026amp;title=Run+a+Function+in+Batch\u0026amp;description=Execute+a+published+Function+asynchronously+over+inline+or+remote+inputs.\u0026amp;theme=f9722fee9e8f402d13bdb22b\u0026amp;signature=9e313e6a15763d76180183273210767061ce129bc1cf87a086721d1b15bde02a\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"https://mintlify.s3.us-west-1.amazonaws.com/sutro-d5dc9f29/_generated/favicon/browserconfig.xml?v=3\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Sutro Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2457DC\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.sutro.sh/reference/api/running-batch-inference\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/reference/api/running-batch-inference.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.sutro.sh/#organization\",\"name\":\"Sutro Docs\",\"url\":\"https://docs.sutro.sh\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/sutro-d5dc9f29/2FChvrRfipPLBgk-/Logo/sutro-light.svg?fit=max\u0026auto=format\u0026n=2FChvrRfipPLBgk-\u0026q=85\u0026s=d97c22cc3edd64b9889c1397a07aa548\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.sutro.sh#website\",\"name\":\"Sutro Docs\",\"url\":\"https://docs.sutro.sh\",\"publisher\":{\"@id\":\"https://docs.sutro.sh/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.sutro.sh/reference/api/running-batch-inference#webpage\",\"url\":\"https://docs.sutro.sh/reference/api/running-batch-inference\",\"name\":\"Run a Function in Batch\",\"description\":\"Execute a published Function asynchronously over inline or remote inputs.\",\"dateModified\":\"2026-11-16T20:46:32.293Z\",\"isPartOf\":{\"@id\":\"https://docs.sutro.sh#website\"},\"breadcrumb\":{\"@id\":\"https://docs.sutro.sh/reference/api/running-batch-inference#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.sutro.sh/reference/api/running-batch-inference#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"API\",\"item\":\"https://docs.sutro.sh/reference/api/check-api-access\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Run a Function in Batch\",\"item\":\"https://docs.sutro.sh/reference/api/running-batch-inference\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.sutro.sh/reference/api/running-batch-inference#apireference\",\"headline\":\"Run a Function in Batch\",\"name\":\"Run a Function in Batch\",\"description\":\"Execute a published Function asynchronously over inline or remote inputs.\",\"url\":\"https://docs.sutro.sh/reference/api/running-batch-inference\",\"mainEntityOfPage\":{\"@id\":\"https://docs.sutro.sh/reference/api/running-batch-inference#webpage\"},\"dateModified\":\"2026-11-16T20:46:32.293Z\",\"publisher\":{\"@id\":\"https://docs.sutro.sh/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.sutro.sh#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Sutro Docs\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Sutro Docs\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/reference/api/running-batch-inference.md","siteName":"Sutro Docs","nav":{"global":null,"anchors":[{"anchor":"Start","icon":"house","pages":[{"title":"Start","href":""}]},{"anchor":"Functions","icon":"function","pages":[{"title":"Functions","href":"/functions/build"}]},{"anchor":"Batch","icon":"layer-group","pages":[{"title":"Batch","href":"/batch/run-model"}]},{"anchor":"Reference","icon":"code","groups":[{"group":"Product","pages":[{"title":"Current capabilities","href":"/reference/current-capabilities"},{"title":"Deployment","href":"/reference/deployment"},{"title":"Authentication","href":"/reference/authentication"}]},{"group":"MCP","pages":[{"title":"MCP","href":"/reference/mcp"}]},{"group":"Python SDK","pages":[{"title":"Python SDK","href":"/reference/python-sdk/setup"},{"title":"Real-time Functions","href":"/reference/python-sdk/run-function"},{"title":"Functions","href":"/reference/python-sdk/functions"},{"title":"Direct model inference","href":"/reference/python-sdk/batch-inference"},{"title":"Remote inputs","href":"/reference/python-sdk/presigned-s3-inputs"},{"title":"Jobs and results","href":"/reference/python-sdk/job-methods"},{"title":"CLI","href":"/reference/cli/index"}]},{"group":"API","pages":[{"title":"Check API access","api":"GET https://your-sutro-deployment.example.com/v1/try-authentication","href":"/reference/api/check-api-access"},{"title":"Get quotas","api":"GET https://your-sutro-deployment.example.com/v1/get-quotas","href":"/reference/api/get-quotas"},{"title":"Run a Function in real time","api":"POST https://your-sutro-deployment.example.com/v1/functions/{name}/run","description":"Execute a published Function on one input and wait for the answer.","href":"/reference/api/run-function"},{"title":"Run a Function in Batch","api":"POST https://your-sutro-deployment.example.com/v1/batch-inference","href":"/reference/api/running-batch-inference"},{"title":"Recover a Batch submission","api":"GET https://your-sutro-deployment.example.com/v1/batch-submissions/{idempotency_key}","description":"Check ingestion or recover an accepted job after an uncertain submission response.","href":"/reference/api/batch-submissions"},{"title":"Check job status","api":"GET https://your-sutro-deployment.example.com/v1/job-status/{job_id}","href":"/reference/api/job-status"},{"title":"Fetch a job","api":"GET https://your-sutro-deployment.example.com/v1/jobs/{job_id}","href":"/reference/api/fetch-job"},{"title":"Cancel a job","api":"GET https://your-sutro-deployment.example.com/v1/job-cancel/{job_id}","href":"/reference/api/cancel-job"},{"title":"Download job results","api":"GET https://your-sutro-deployment.example.com/v1/jobs/{job_id}/results","href":"/reference/api/job-results"},{"title":"Get a results URL","api":"GET https://your-sutro-deployment.example.com/v1/jobs/{job_id}/results-url","href":"/reference/api/job-results-url"},{"title":"List jobs","api":"GET https://your-sutro-deployment.example.com/v1/list-jobs","href":"/reference/api/list-jobs"}]}]}]},"basePath":"","title":"Run a Function in Batch - Sutro Docs","deploymentId":"dpl_FZMKUpaaKiVETbfqhoUe4sPFDTmY","buildId":"dpl_FZMKUpaaKiVETbfqhoUe4sPFDTmY","dynamics":["c2aa737661","2b790eda92","b0f84f53ff"],"chunks":["OpenApiReferenceProvider-B6WFFOBL.js","utils-BN5um1KA.js","cloneDeep-C3md22mN.js","_Uint8Array-DLlL8L26.js","isObject-FP1Yky1u.js","utils-BSmbkXJR.js","addUniqueKeysToSchema-2tqcVnUE.js","snippetPresets-CtWfvr2J.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-DkKHBy30.js","isEqual-O3q7y6pq.js","usePlaygroundInputsStore-Brc5H9UJ.js","shallow-C4L4xvbs.js","getApiPlaygroundDisplay-2bxyq_aI.js","CodeSnippet-BJu8ddd5.js","CodeSnippets-dazWmoqB.js","Page-CnLhKuUV.js","getPastedJson-Chy3Qa1S.js","icon-CyO7h3jh.js","MethodPill-Dle0_91v.js","DuplicateIcon-CVvWAf4a.js","createIcon-Di07A27B.js","DynamicMarkdown-C4w9kavL.js","SectionHeading-XiBebVYC.js","axios-vUo_bRtp.js"]}