You have a list — candidate properties, a portfolio, a county’s worth of
addresses — and you want the same screen over all of them. This is
/v1/fetch applied to up to 25 locations in one
request: one field selection, N locations, index-aligned results.If you have one location, use /v1/fetch. If your list is bigger than 25,
page it — the bound exists so one request cannot stampede the ~84 upstream
sources every location fans out to.
Each entry in locations is the exact locator contract of /v1/fetch:
lat+lngoraddress, never both. The field selection (fields and/or
preset) is batch-wide by design — the batch exists for “the same screen over
a list”, and per-location field lists would make the response shape
unpredictable for exactly the clients (agents, spreadsheets) it serves.
Results are index-aligned with the request.results[i] answers
locations[i], always, and carries index explicitly so a filtered or
logged entry stays attributable.
Each ok: true entry is a /v1/fetch response body. Same fields
shape, same tri-state field status, same partial_failures, same
geocode echo when the location was an address. A client that parses the
single endpoint parses the batch with no new code.
A location’s failure is an entry, never an HTTP failure. Location #7’s
bad address cannot cost you the other 24 results: it becomes
{"ok": false, "error": {…}} with the same error object (error,
message, retryable) the single endpoint would have returned for that
location — one error-handling code path for both endpoints.
Entry-level (ok: false): the location itself failed — the address
didn’t geocode, the coordinate is outside the US envelope, or the worker
shed the location at capacity (fetch_busy, retryable).
Field-level (partial_failures inside an ok: true entry): the
location was fine, but individual fields failed upstream — identical
semantics to /v1/fetch.
A batch-level HTTP error is reserved for the caller’s own mistakes, which are
identical for every location: unknown field names (400 fields_unknown), no
fields (400 no_fields_requested), too many explicit fields
(400 fields_too_many), an over-long list (422), or a malformed locator
(422).
The /v1/fetch field rules apply unchanged: 50 explicit fields max,
presets exempt.
Locations are processed 4 at a time inside the batch, and every location
counts against the same per-worker admission gate as a single /v1/fetch —
a batch is 25 requests’ worth of work and is metered as such, not smuggled
under one admission slot. A location shed at capacity returns as an
ok: falsefetch_busy entry (retryable) rather than failing the batch.
Worst-case latency ≈ 90 s (every location cold, every source at its
budget). Typical is far lower, but set your client timeout to 120 s+,
same guidance as /v1/ask.
Public Fetch and included address resolution are free. Every location still
consumes request and source capacity. Parcel-dependent fields require Enrich.
Batch is REST-only for now: the MCP mireye_fetch tool stays
single-location (agents iterate naturally), and MCP hosts impose their own
tool-response size limits a 25-location payload would fight.
Billing commits per location as it computes, and the response arrives as
one JSON body at the end — so a response lost in transit (a gateway 502, a
client read timeout) would otherwise mean paying for results you never
received. The Idempotency-Key header closes that gap:
Shape: 8–128 characters of [A-Za-z0-9_-]. Use a fresh key per
distinct batch (a run id, a UUID).
On a lost response, retry with the SAME key and the SAME body. If the
original computation finished server-side, you get the already-computed
result back at zero additional charge, marked "replayed": true. The
stored result lives 24 hours.
409 batch_in_progress (with Retry-After): your retry raced the
original computation — it is still running server-side. Wait and retry
with the same key; do not switch keys (that recomputes and re-bills).
409 idempotency_key_reused: the key was already used with a
different request body. Keys pin the exact batch they answered.
Replays are free of credit charges but still count against your
per-minute rate limit — a replay is a request.
The header is optional; requests without it behave exactly as before.
For batches where you would rather not hold an HTTP connection at all, use
POST /v1/runs (kind: fetch_batch) — submit, poll,
and collect results; it survives disconnects by design.
The field selection is deliberately batch-wide, not per-location: the
batch exists for "the same screen over a list of candidate properties",
and per-location field lists would make the response shape unpredictable
for exactly the clients (agents, spreadsheets) the batch serves.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Mireye","colors":{"primary":"#0E5C2F","light":"#16A34A","dark":"#0B3D20"},"logo":{"light":"https://mintcdn.com/mireye-58181a65/zsiO7l6DvQLXFAXi/logo/light.svg?fit=max\u0026auto=format\u0026n=zsiO7l6DvQLXFAXi\u0026q=85\u0026s=5714ed8c487b8165cfac87be383944d9","dark":"https://mintcdn.com/mireye-58181a65/zsiO7l6DvQLXFAXi/logo/dark.svg?fit=max\u0026auto=format\u0026n=zsiO7l6DvQLXFAXi\u0026q=85\u0026s=b74f4ca2835aa4896c1052864f9092ee"},"favicon":"https://mintcdn.com/mireye-58181a65/zsiO7l6DvQLXFAXi/favicon.svg?fit=max\u0026auto=format\u0026n=zsiO7l6DvQLXFAXi\u0026q=85\u0026s=c2bb1398d848c317b12624bc2aafbdbd","api":{"openapi":"openapi.json"},"navbar":{"links":[{"href":"https://www.mireye.com/pricing","label":"Pricing"},{"href":"https://github.com/Mireye-Labs/mireye-earth","label":"GitHub"}],"primary":{"type":"button","label":"Get an API key","href":"https://www.mireye.com/signup"}},"footer":{"socials":{"github":"https://github.com/Mireye-Labs/mireye-earth"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"mireye-58181a65","hasAudioNarration":false,"actualSubdomain":"mireye-58181a65","customDomains":["docs.mireye.ai"],"gitSource":{"type":"github","owner":"mireye-labs","repo":"mireye-earth","deployBranch":"main","contentDirectory":"docs","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6ae520f9b15bd07e863cbec6","collectionId":"3d482111-be22-467a-89db-b84b6c858677","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6ae520f9b15bd07e863cbec6"},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"REMOVE_BRANDING":{"status":"ENABLED"},"CONTEXTUAL_FEEDBACK":{"status":"ENABLED"},"CODE_SNIPPET_FEEDBACK":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6ae520f9b15bd07e863cbec6","clientVersion":"0.0.4044","searchFilterCounts":[{"language":"default","tag":"API reference","count":26},{"language":"default","tag":"Discover parcels","count":6},{"language":"default","tag":"MCP","count":6},{"language":"default","tag":"Guides","count":5},{"language":"default","tag":"Catalog","count":4},{"language":"default","tag":"Get started","count":4},{"language":"default","tag":"Fetch","count":3},{"language":"default","tag":"Runs","count":3},{"language":"default","tag":"Reference","count":2},{"language":"default","tag":"Ask","count":2}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","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":"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":"llms-txt-v2","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":"byok-sep-25","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":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","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":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/fetch-batch","slug":"/api-reference/fetch-batch","pageMetadata":{"title":"POST /v1/fetch/batch","description":"The same field fetch for up to 25 locations in one request.","openapi":"POST /v1/fetch/batch","href":"/api-reference/fetch-batch"},"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: \"The same field fetch for up to 25 locations in one request.\"\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`,em:`em`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`2`,id:`when-to-use-this`,children:`When to use this`}),`\n`,_jsxs(_components.p,{children:[`You have a list — candidate properties, a portfolio, a county’s worth of\naddresses — and you want the same screen over all of them. This is\n`,_jsx(_components.a,{href:`/api-reference/fetch`,children:_jsx(_components.code,{children:`/v1/fetch`})}),` applied to up to `,_jsx(_components.strong,{children:`25 locations`}),` in one\nrequest: one field selection, N locations, index-aligned results.`]}),`\n`,_jsxs(_components.p,{children:[`If you have one location, use `,_jsx(_components.code,{children:`/v1/fetch`}),`. If your list is bigger than 25,\npage it — the bound exists so one request cannot stampede the ~84 upstream\nsources every location fans out to.`]}),`\n`,_jsx(Heading,{level:`2`,id:`request`,children:`Request`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`11`,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:`11`,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:` -s`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://api.mireye.com/v1/fetch/batch`}),_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: Bearer `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`$MIREYE_API_TOKEN`}),_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:` \"locations\": [`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` {\"lat\": 29.7604, \"lng\": -95.3698},`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` {\"address\": \"350 5th Ave, New York, NY 10118\"},`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` {\"lat\": 39.7392, \"lng\": -104.9903}`})}),`\n`,_jsx(_components.span,{className:`line`,children:_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:` \"fields\": [\"elevation\", \"coast_distance_m\"]`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` }'`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` |`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:` jq`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Each entry in `,_jsx(_components.code,{children:`locations`}),` is the exact locator contract of `,_jsx(_components.code,{children:`/v1/fetch`}),`:\n`,_jsx(_components.code,{children:`lat`}),`+`,_jsx(_components.code,{children:`lng`}),` `,_jsx(_components.strong,{children:`or`}),` `,_jsx(_components.code,{children:`address`}),`, never both. The field selection (`,_jsx(_components.code,{children:`fields`}),` and/or\n`,_jsx(_components.code,{children:`preset`}),`) is batch-wide by design — the batch exists for “the same screen over\na list”, and per-location field lists would make the response shape\nunpredictable for exactly the clients (agents, spreadsheets) it serves.`]}),`\n`,_jsx(Heading,{level:`2`,id:`response`,children:`Response`}),`\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:` \"fetched_at\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2026-07-27T09:00:00+00:00\"`}),_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:`: [`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"index\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`0`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"ok\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`true`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"lat\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`29.7604`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"lng\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`-95.3698`}),_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:` \"fetched_at\"`}),_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:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"fields\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"…\"`}),_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:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"partial_failures\"`}),_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:` \"resolved_location\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"lat\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`29.7604`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"lng\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`-95.3698`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"source\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"coordinate\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}},`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"index\"`}),_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:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"ok\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`true`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"lat\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`40.748377`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"lng\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`-73.984854`}),_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:` \"fetched_at\"`}),_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:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"fields\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"…\"`}),_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:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"partial_failures\"`}),_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:` \"geocode\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"accuracy_type\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"rooftop\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"…\"`}),_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:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`},`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"resolved_location\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"lat\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`40.748377`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"lng\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`-73.984854`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"source\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"address\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}},`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` {`}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"index\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`2`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"ok\"`}),_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:` \"error\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"error\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"coord_out_of_bounds\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},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:`\"…\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},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`}),_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`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`Three properties to build on:`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Results are index-aligned with the request.`}),` `,_jsx(_components.code,{children:`results[i]`}),` answers\n`,_jsx(_components.code,{children:`locations[i]`}),`, always, and carries `,_jsx(_components.code,{children:`index`}),` explicitly so a filtered or\nlogged entry stays attributable.`]}),`\n`,_jsxs(_components.li,{children:[_jsxs(_components.strong,{children:[`Each `,_jsx(_components.code,{children:`ok: true`}),` entry is a `,_jsx(_components.code,{children:`/v1/fetch`}),` response body.`]}),` Same `,_jsx(_components.code,{children:`fields`}),`\nshape, same tri-state field `,_jsx(_components.code,{children:`status`}),`, same `,_jsx(_components.code,{children:`partial_failures`}),`, same\n`,_jsx(_components.code,{children:`geocode`}),` echo when the location was an address. A client that parses the\nsingle endpoint parses the batch with no new code.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`A location’s failure is an entry, never an HTTP failure.`}),` Location #7’s\nbad address cannot cost you the other 24 results: it becomes\n`,_jsx(_components.code,{children:`{\"ok\": false, \"error\": {…}}`}),` with the same error object (`,_jsx(_components.code,{children:`error`}),`,\n`,_jsx(_components.code,{children:`message`}),`, `,_jsx(_components.code,{children:`retryable`}),`) the single endpoint would have returned for that\nlocation — one error-handling code path for both endpoints.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`two-levels-of-partial-failure`,children:`Two levels of partial failure`}),`\n`,_jsx(_components.p,{children:`Don’t conflate them:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Entry-level`}),` (`,_jsx(_components.code,{children:`ok: false`}),`): the location itself failed — the address\ndidn’t geocode, the coordinate is outside the US envelope, or the worker\nshed the location at capacity (`,_jsx(_components.code,{children:`fetch_busy`}),`, retryable).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Field-level`}),` (`,_jsx(_components.code,{children:`partial_failures`}),` inside an `,_jsx(_components.code,{children:`ok: true`}),` entry): the\nlocation was fine, but individual fields failed upstream — identical\nsemantics to `,_jsx(_components.code,{children:`/v1/fetch`}),`.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`A batch-level HTTP error is reserved for the caller’s own mistakes, which are\nidentical for every location: unknown field names (`,_jsx(_components.code,{children:`400 fields_unknown`}),`), no\nfields (`,_jsx(_components.code,{children:`400 no_fields_requested`}),`), too many explicit fields\n(`,_jsx(_components.code,{children:`400 fields_too_many`}),`), an over-long list (`,_jsx(_components.code,{children:`422`}),`), or a malformed locator\n(`,_jsx(_components.code,{children:`422`}),`).`]}),`\n`,_jsx(Heading,{level:`2`,id:`limits`,children:`Limits`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`25 locations maximum`}),` per request (`,_jsx(_components.code,{children:`422`}),` above it).`]}),`\n`,_jsxs(_components.li,{children:[_jsxs(_components.strong,{children:[`The `,_jsx(_components.code,{children:`/v1/fetch`}),` field rules apply unchanged`]}),`: 50 explicit fields max,\npresets exempt.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Locations are processed 4 at a time`}),` inside the batch, and every location\ncounts against the same per-worker admission gate as a single `,_jsx(_components.code,{children:`/v1/fetch`}),` —\na batch is 25 requests’ worth of work and is metered as such, not smuggled\nunder one admission slot. A location shed at capacity returns as an\n`,_jsx(_components.code,{children:`ok: false`}),` `,_jsx(_components.code,{children:`fetch_busy`}),` entry (retryable) rather than failing the batch.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Worst-case latency ≈ 90 s`}),` (every location cold, every source at its\nbudget). Typical is far lower, but set your client timeout to `,_jsx(_components.strong,{children:`120 s+`}),`,\nsame guidance as `,_jsx(_components.code,{children:`/v1/ask`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Public Fetch and included address resolution are free.`}),` Every location still\nconsumes request and source capacity. Parcel-dependent fields require Enrich.`]}),`\n`,_jsxs(_components.li,{children:[`Batch is `,_jsx(_components.strong,{children:`REST-only`}),` for now: the MCP `,_jsx(_components.code,{children:`mireye_fetch`}),` tool stays\nsingle-location (agents iterate naturally), and MCP hosts impose their own\ntool-response size limits a 25-location payload would fight.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`retries-and-lost-responses-idempotency-key`,children:`Retries and lost responses (Idempotency-Key)`}),`\n`,_jsxs(_components.p,{children:[`Billing commits `,_jsx(_components.strong,{children:`per location as it computes`}),`, and the response arrives as\none JSON body at the end — so a response lost in transit (a gateway `,_jsx(_components.code,{children:`502`}),`, a\nclient read timeout) would otherwise mean paying for results you never\nreceived. The `,_jsx(_components.code,{children:`Idempotency-Key`}),` header closes that gap:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,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:`5`,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:` -X`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` POST`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://api.mireye.com/v1/fetch/batch`}),_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: Bearer `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`$MIREYE_API_TOKEN`}),_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:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Idempotency-Key: site-screen-2026-08-07-run1\"`}),_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:` '{\"locations\": [...], \"fields\": [\"elevation\"]}'`})]}),`\n`]})})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Shape:`}),` 8–128 characters of `,_jsx(_components.code,{children:`[A-Za-z0-9_-]`}),`. Use a fresh key per\ndistinct batch (a run id, a UUID).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`On a lost response, retry with the SAME key and the SAME body.`}),` If the\noriginal computation finished server-side, you get the already-computed\nresult back at `,_jsx(_components.strong,{children:`zero additional charge`}),`, marked `,_jsx(_components.code,{children:`\"replayed\": true`}),`. The\nstored result lives `,_jsx(_components.strong,{children:`24 hours`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:_jsx(_components.code,{children:`409 batch_in_progress`})}),` (with `,_jsx(_components.code,{children:`Retry-After`}),`): your retry raced the\noriginal computation — it is still running server-side. Wait and retry\nwith the same key; do not switch keys (that recomputes and re-bills).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:_jsx(_components.code,{children:`409 idempotency_key_reused`})}),`: the key was already used with a\n`,_jsx(_components.em,{children:`different`}),` request body. Keys pin the exact batch they answered.`]}),`\n`,_jsxs(_components.li,{children:[`Replays are free of credit charges but `,_jsx(_components.strong,{children:`still count against your\nper-minute rate limit`}),` — a replay is a request.`]}),`\n`,_jsx(_components.li,{children:`The header is optional; requests without it behave exactly as before.`}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`For batches where you would rather not hold an HTTP connection at all, use\n`,_jsx(_components.a,{href:`/api-reference/runs`,children:_jsx(_components.code,{children:`POST /v1/runs`})}),` (`,_jsx(_components.code,{children:`kind: fetch_batch`}),`) — submit, poll,\nand collect results; it survives disconnects by design.`]})]})}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":"POST /v1/fetch/batch","description":"The same field fetch for up to 25 locations in one request.","openapi":"POST /v1/fetch/batch","href":"/api-reference/fetch-batch"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"When to use this","slug":"when-to-use-this","depth":2,"children":[]},{"title":"Request","slug":"request","depth":2,"children":[]},{"title":"Response","slug":"response","depth":2,"children":[]},{"title":"Two levels of partial failure","slug":"two-levels-of-partial-failure","depth":2,"children":[]},{"title":"Limits","slug":"limits","depth":2,"children":[]},{"title":"Retries and lost responses (Idempotency-Key)","slug":"retries-and-lost-responses-idempotency-key","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"description":"The same field fetch for up to 25 locations in one request.","operationId":"fetch_batch_v1_fetch_batch_post","parameters":["deee42e2-6275-4613-9180-5c19461d491e"],"requestBody":"04621dcb-a15a-453a-a683-835a7e902ae2","responses":{"200":"00c64d82-f323-410b-9acb-bf3e66f99a68","422":"33447574-c525-4a49-9caf-578f54804eee"},"summary":"Fetch fields for up to 25 locations in one request","method":"post","type":"path","servers":["d3c9b39c-06f5-41a7-a7c7-9a02a9ccae06"],"security":[],"path":"/v1/fetch/batch","baseUrlOptions":["https://api.mireye.com"],"title":"Fetch fields for up to 25 locations in one request","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"deee42e2-6275-4613-9180-5c19461d491e":{"in":"header","name":"Idempotency-Key","required":false,"schema":{"oneOf":[{"type":"string","title":"Idempotency-Key","uniqueKey":"oneOf.0","typeLabel":"string"},{"type":"null","title":"Idempotency-Key","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"string | null"}}},"requestBody":{"content":{"application/json":{"schema":{"description":"N locations, one field selection.\n\nThe field selection is deliberately batch-wide, not per-location: the\nbatch exists for \"the same screen over a list of candidate properties\",\nand per-location field lists would make the response shape unpredictable\nfor exactly the clients (agents, spreadsheets) the batch serves.","properties":{"locations":{"items":{"description":"One batch entry — the exact locator contract of /v1/fetch.","properties":{"address":{"oneOf":[{"type":"string","title":"Address","maxLength":256,"minLength":1,"uniqueKey":"locations.items.[INDEX].address.oneOf.0","typeLabel":"string"},{"type":"null","title":"Address","uniqueKey":"locations.items.[INDEX].address.oneOf.1","typeLabel":"null"}],"uniqueKey":"locations.items.[INDEX].address","typeLabel":"string | null"},"lat":{"oneOf":[{"type":"number","title":"Lat","uniqueKey":"locations.items.[INDEX].lat.oneOf.0","typeLabel":"number"},{"type":"null","title":"Lat","uniqueKey":"locations.items.[INDEX].lat.oneOf.1","typeLabel":"null"}],"uniqueKey":"locations.items.[INDEX].lat","typeLabel":"number | null"},"lng":{"oneOf":[{"type":"number","title":"Lng","uniqueKey":"locations.items.[INDEX].lng.oneOf.0","typeLabel":"number"},{"type":"null","title":"Lng","uniqueKey":"locations.items.[INDEX].lng.oneOf.1","typeLabel":"null"}],"uniqueKey":"locations.items.[INDEX].lng","typeLabel":"number | null"}},"title":"BatchFetchLocation","type":"object","uniqueKey":"locations.items.[INDEX]","typeLabel":"BatchFetchLocation · object"},"maxItems":25,"minItems":1,"title":"Locations","type":"array","isRequired":true,"uniqueKey":"locations","typeLabel":"BatchFetchLocation · object[]"},"fields":{"oneOf":[{"type":"array","items":{"type":"string","uniqueKey":"fields.oneOf.0.items.[INDEX]","typeLabel":"string"},"title":"Fields","uniqueKey":"fields.oneOf.0","typeLabel":"string[]"},{"type":"null","title":"Fields","uniqueKey":"fields.oneOf.1","typeLabel":"null"}],"uniqueKey":"fields","typeLabel":"string[] | null"},"preset":{"oneOf":[{"type":"string","title":"Preset","enum":["terrain","flood_risk","wildfire_underwrite","land_cover","site_selection","building_lookup","points_of_interest","utilities","boundaries","solar_siting","wind_siting","storage_siting","data_center_siting","grid_interconnect","natural_hazard"],"uniqueKey":"preset.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","title":"Preset","uniqueKey":"preset.oneOf.1","typeLabel":"null"}],"uniqueKey":"preset","typeLabel":"enum\u003cstring> | null"}},"required":["locations"],"title":"BatchFetchRequest","type":"object","uniqueKey":"","typeLabel":"BatchFetchRequest · object"},"examples":{"Example":{"title":"Example","value":{"locations":[{"address":"\u003cstring>","lat":123,"lng":123}],"fields":["\u003cstring>"]}}},"exampleType":"generated"}},"required":true,"exampleType":"generated"},"responses":{"00c64d82-f323-410b-9acb-bf3e66f99a68":{"content":{"application/json":{"schema":{}}},"description":"Successful Response","exampleType":"generated"},"33447574-c525-4a49-9caf-578f54804eee":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"oneOf":[{"type":"string","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.0","typeLabel":"string"},{"type":"integer","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.1","typeLabel":"integer"}],"uniqueKey":"detail.items.[INDEX].loc.items.[INDEX]","typeLabel":"string | integer"},"title":"Location","type":"array","isRequired":true,"uniqueKey":"detail.items.[INDEX].loc","typeLabel":"(string | integer)[]"},"msg":{"title":"Message","type":"string","isRequired":true,"uniqueKey":"detail.items.[INDEX].msg","typeLabel":"string"},"type":{"title":"Error Type","type":"string","isRequired":true,"uniqueKey":"detail.items.[INDEX].type","typeLabel":"string"},"ctx":{"title":"Context","type":"object","uniqueKey":"detail.items.[INDEX].ctx","typeLabel":"Context · object"},"input":{"oneOf":[{"title":"Input"}],"uniqueKey":"detail.items.[INDEX].input","typeLabel":"any"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object","uniqueKey":"detail.items.[INDEX]","typeLabel":"ValidationError · object"},"title":"Detail","type":"array","uniqueKey":"detail","typeLabel":"ValidationError · object[]"}},"title":"HTTPValidationError","type":"object","uniqueKey":"","typeLabel":"HTTPValidationError · object"},"examples":{"Example":{"title":"Example","value":{"detail":[{"loc":["\u003cstring>"],"msg":"\u003cstring>","type":"\u003cstring>","ctx":{},"input":"\u003cunknown>"}]}}},"exampleType":"generated"}},"description":"Validation Error","exampleType":"generated"}},"security":{},"servers":{"d3c9b39c-06f5-41a7-a7c7-9a02a9ccae06":{"description":"Production","url":"https://api.mireye.com"}}},"originalFileLocation":"openapi.json"},"subdomain":"mireye-58181a65","siteName":"Mireye","title":"POST /v1/fetch/batch - Mireye","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-20T23:35:36.856Z","originalFileLocation":"api-reference/fetch-batch.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=\"The same field fetch for up to 25 locations in one request.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Mireye\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/mireye-58181a65/IkcLneXO-Xfm7c2i/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/mireye-58181a65/IkcLneXO-Xfm7c2i/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/mireye-58181a65/IkcLneXO-Xfm7c2i/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/mireye-58181a65/IkcLneXO-Xfm7c2i/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/mireye-58181a65/IkcLneXO-Xfm7c2i/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/mireye-58181a65/IkcLneXO-Xfm7c2i/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/mireye-58181a65/IkcLneXO-Xfm7c2i/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/mireye-58181a65/IkcLneXO-Xfm7c2i/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/mireye-58181a65/IkcLneXO-Xfm7c2i/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"POST /v1/fetch/batch - Mireye\">\u003cmeta data-mint-head property=\"og:description\" content=\"The same field fetch for up to 25 locations in one request.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Mireye\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.mireye.ai/api-reference/fetch-batch\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://mireye-58181a65.mintlify.app/_mintlify/api/og/v2?division=Fetch\u0026amp;title=POST+%2Fv1%2Ffetch%2Fbatch\u0026amp;description=The+same+field+fetch+for+up+to+25+locations+in+one+request.\u0026amp;theme=22c86cabea284b30e354f833\u0026amp;signature=fb38c6a2e9f984bbdce50ca50f61438df27510e15109130157dd3775c48f08a1\">\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=\"POST /v1/fetch/batch - Mireye\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"The same field fetch for up to 25 locations in one request.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://mireye-58181a65.mintlify.app/_mintlify/api/og/v2?division=Fetch\u0026amp;title=POST+%2Fv1%2Ffetch%2Fbatch\u0026amp;description=The+same+field+fetch+for+up+to+25+locations+in+one+request.\u0026amp;theme=22c86cabea284b30e354f833\u0026amp;signature=fb38c6a2e9f984bbdce50ca50f61438df27510e15109130157dd3775c48f08a1\">\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=\"/mintlify-assets/_mintlify/favicons/mireye-58181a65/IkcLneXO-Xfm7c2i/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Mireye\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0E5C2F\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.mireye.ai/api-reference/fetch-batch\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/fetch-batch.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.mireye.ai/#organization\",\"name\":\"Mireye\",\"url\":\"https://docs.mireye.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/mireye-58181a65/zsiO7l6DvQLXFAXi/logo/light.svg?fit=max\u0026auto=format\u0026n=zsiO7l6DvQLXFAXi\u0026q=85\u0026s=5714ed8c487b8165cfac87be383944d9\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.mireye.ai#website\",\"name\":\"Mireye\",\"url\":\"https://docs.mireye.ai\",\"publisher\":{\"@id\":\"https://docs.mireye.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.mireye.ai/api-reference/fetch-batch#webpage\",\"url\":\"https://docs.mireye.ai/api-reference/fetch-batch\",\"name\":\"POST /v1/fetch/batch\",\"description\":\"The same field fetch for up to 25 locations in one request.\",\"dateModified\":\"2026-10-20T23:35:36.856Z\",\"isPartOf\":{\"@id\":\"https://docs.mireye.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.mireye.ai/api-reference/fetch-batch#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.mireye.ai/api-reference/fetch-batch#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Fetch\",\"item\":\"https://docs.mireye.ai/api-reference/fetch\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"POST /v1/fetch/batch\",\"item\":\"https://docs.mireye.ai/api-reference/fetch-batch\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.mireye.ai/api-reference/fetch-batch#apireference\",\"headline\":\"POST /v1/fetch/batch\",\"name\":\"POST /v1/fetch/batch\",\"description\":\"The same field fetch for up to 25 locations in one request.\",\"url\":\"https://docs.mireye.ai/api-reference/fetch-batch\",\"mainEntityOfPage\":{\"@id\":\"https://docs.mireye.ai/api-reference/fetch-batch#webpage\"},\"dateModified\":\"2026-10-20T23:35:36.856Z\",\"publisher\":{\"@id\":\"https://docs.mireye.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.mireye.ai#website\"}}]}\u003c/script>","siteName":"Mireye","nav":{"global":null,"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":"/introduction"}]},{"tab":"API reference","icon":"rectangle-terminal","groups":[{"group":"Ask","pages":[{"title":"POST /v1/ask","openapi":"POST /v1/ask","href":"/api-reference/ask"},{"title":"POST /v1/ask/stream","openapi":"POST /v1/ask/stream","href":"/api-reference/ask-stream"}]},{"group":"Fetch","pages":[{"title":"POST /v1/fetch","openapi":"POST /v1/fetch","href":"/api-reference/fetch"},{"title":"POST /v1/x402/fetch","description":"Pay per call with USDC on Base for cited public geospatial facts. No Mireye API key required.","openapi":"POST /v1/x402/fetch","href":"/api-reference/x402-fetch"},{"title":"POST /v1/fetch/batch","openapi":"POST /v1/fetch/batch","href":"/api-reference/fetch-batch"}]},{"group":"Runs","pages":[{"title":"POST /v1/runs","description":"Submit a job, get a run_id immediately, poll or stream its progress.","openapi":"POST /v1/runs","href":"/api-reference/runs"},{"title":"GET /v1/runs/{run_id}/events","openapi":"GET /v1/runs/{run_id}/events","href":"/api-reference/run-events"},{"title":"GET /v1/runs/{run_id}/artifacts/{fmt}","openapi":"GET /v1/runs/{run_id}/artifacts/{fmt}","href":"/api-reference/run-artifacts"}]},{"group":"Sites","pages":[{"title":"Prepare a site","openapi":"POST /v1/sites","href":"/api-reference/sites"},{"title":"POST /v1/ask-site","openapi":"POST /v1/ask-site","href":"/api-reference/ask-site"}]},{"group":"Location utilities","pages":[{"title":"POST /v1/geocode","openapi":"POST /v1/geocode","href":"/api-reference/geocode"},{"title":"POST /v1/proximity","openapi":"POST /v1/proximity","href":"/api-reference/proximity"}]},{"group":"Discover parcels","pages":[{"title":"POST /v1/search","openapi":"POST /v1/search","href":"/api-reference/search"},{"title":"Searchable fields","href":"/api-reference/search-fields"},{"title":"GET /v1/search/fields","openapi":"GET /v1/search/fields","href":"/api-reference/get-search-fields"},{"title":"POST /v1/enrich","openapi":"POST /v1/enrich","href":"/api-reference/enrich"},{"title":"Enrich fields","href":"/api-reference/enrich-fields"},{"title":"GET /v1/enrich/fields","openapi":"GET /v1/enrich/fields","href":"/api-reference/get-enrich-fields"}]},{"group":"Catalog","pages":[{"title":"GET /v1/meta/fields","openapi":"GET /v1/meta/fields","href":"/api-reference/meta-fields"},{"title":"Field catalog","href":"/api-reference/field-catalog"},{"title":"POST /v1/field-requests","openapi":"POST /v1/field-requests","href":"/api-reference/field-requests"},{"title":"GET /v1/field-requests/{request_id}","openapi":"GET /v1/field-requests/{request_id}","href":"/api-reference/field-requests-status"}]},{"group":"Reference","pages":[{"title":"Errors","href":"/api-reference/errors"},{"title":"Agent onboarding API","href":"/api-reference/agent-onboarding"}]},{"group":"Migration","pages":[{"title":"Lookup and Resolve migration","href":"/api-reference/lookup"},{"title":"Fetch quote compatibility","href":"/api-reference/fetch-quote"}]}]},{"tab":"MCP","icon":"plug","pages":[{"title":"MCP","href":"/mcp/installation"}]}]},"basePath":"","title":"POST /v1/fetch/batch - Mireye","buildId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","deploymentId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-CS552b7R.js","utils-DDTCYAF2.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-De8ttokP.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-DrwRDvAh.js","snippetPresets-DtAN0nWx.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-D5rWArI6.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-O2i12wsz.js","shallow-DV8xABTt.js","getApiPlaygroundDisplay-DBZ0B5Jx.js","CodeSnippet-BVi0tPUX.js","CodeSnippets-CqASbIwY.js","Page-m07pfKpT.js","getPastedJson-DG9vsMS8.js","icon-CXzRSCr8.js","MethodPill-BdKVtEuX.js","DuplicateIcon-CZlmBrJI.js","createIcon-biFEUKPL.js","DynamicMarkdown-B54_zNBF.js","SectionHeading-DwwHK3Pt.js","axios-vUo_bRtp.js","Markdown-DfhCTwyA.js","clsx-xpJZXxdP.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-BTZUMDnx.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-DqdKa2R4.js"]}