InstaMaps Runs and jobs API
The Runs and jobs API from InstaMaps — 3 operation(s) for runs and jobs.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/get-instamaps-com:get-instamaps-com-runs-and-jobs-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: InstaMaps Runs and jobs API
version: 0.6.0
description: 'Location data for lists, as one REST endpoint per job: geocode with a confidence per row, straight-line and road distances,
multi-driver route plans, drive-time areas, official facts (census tract, HUBZone, flood zones), flood, crime and natural-hazard
risk, live warnings, places nearby, plain-English questions over a table, and hosted maps. Strongest in the US and Great Britain,
on our own address index, roads and official data. The same tools as the InstaMaps MCP server, as plain HTTP.
**Auth.** Authorization: Bearer (or X-API-Key). Keys are free: sign in with Google at /developers/portal.
**Free.** 2,500 lookups a day per account, every endpoint, reset at midnight UTC. No card.
**What counts as a lookup.**
- One lookup per row a call carries: an address placed, a journey measured, a stop routed, a place checked.
- A question to ask_table is 10 lookups, however long the table.
- A drive-time area is 10 lookups a band, plus one per place checked against it.
- Maps, live hazards and postcode-radius lists are one lookup a call. Checking a background job (get_job) is free.
- Rows sent by reference (a Google Sheet, a Drive file or an earlier run) are counted from the answer.
**Keep what you get.** No 30-day cache rule: store the results in your own database for as long as you like. Every answer names its sources and their dates.
**Every answer:**
- Nothing is dropped: every row sent comes back, in order, under your own id; rows that cannot be placed or answered say why. An answer that would lose rows fails loudly instead.
- Every row carries confidence {level: high | medium | low, score, basis}; basis is a stable code (rooftop, postcode_centre, not_placed…) and the answer''s confidence object says what each basis present means and what to do about it.
- Every row carries record_key, the same place ID from every tool, so answers from different tools join on it.
- Every answer ends with a run block: when, how many rows, sources with their dates, the confidence counts, calls used and left today, and a run_id that any tool can take as source {run} and render_map as from_run.
- Lists by reference: pass a Google Sheet, a Drive file or a run_id instead of typing rows. Every tool but one only reads; write_to_sheet puts an answer into the sheet as new dated columns or a new tab, never overwriting.
- No vendor or model names in answers; every source is named with its date.
Docs: https://get-instamaps.com/developers'
contact:
name: InstaMaps
email: hello@get-instamaps.com
url: https://get-instamaps.com/developers
termsOfService: https://get-instamaps.com/terms
servers:
- url: https://get-instamaps.com
description: InstaMaps
security:
- apiKey: []
tags:
- name: Runs and jobs
paths:
/v1/combine_runs:
post:
operationId: combine_runs
summary: Join two to six kept runs on the place ID every tool returns (record_key) and…
description: 'Join two to 6 kept runs (run_ids from earlier answers, or tables such as dated tabs in Drive) on the place ID every tool returns (record_key), each run''s columns kept separate under its name, and say what changed between the first and last run for the columns named in compare: "sites whose nearest A&E got further away since September". Places in only some runs are kept and say which; only_changed returns just the rows that changed. Up to 5,000 rows a run; the first 300 combined rows come back.
Use when:
- "Which sites'' nearest A&E got further away since September?"
- Merging geocode results with facts or risk for the same places
Coverage: Any runs from earlier answers (run_ids) or tables you send.
Reference: https://get-instamaps.com/mcp-server/tools/combine_runs'
tags:
- Runs and jobs
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
runs:
type: array
minItems: 2
maxItems: 6
items:
anyOf:
- type: string
description: A run_id from an earlier answer.
- type: object
properties:
name:
type: string
description: e.g. "hospitals · 2026-09-12".
run_id:
type: string
rows:
type: array
items:
type: object
description: Oldest first.
key:
type: string
default: record_key
description: The place ID column every run has.
columns:
type: array
items:
type: string
description: 'Only these columns from each run (default: all).'
compare:
type: array
items:
type: string
description: 'Columns to compare between runs: numbers get the change, text whether it changed.'
only_changed:
type: boolean
default: false
required:
- runs
example:
runs:
- run_… (geocode_batch)
- run_… (get_area_risk flood)
key: record_key
responses:
'200':
description: 'The answer. For example: "2 places across 2 runs, 2 in every run"'
headers:
X-Lookups-Used:
schema:
type: integer
description: Lookups this call cost.
X-Lookups-Remaining:
schema:
type: integer
description: Free lookups left today.
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The answer in one or two sentences.
additionalProperties: true
'400':
description: The request could not be answered; error says why.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'401':
description: No API key, or an unknown or revoked one.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'404':
description: No such endpoint.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'429':
description: Today's free lookups are used up (or the call needs more than are left), or too many requests a minute.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
/v1/get_job:
post:
operationId: get_job
summary: 'How far a background job has got: status, rows done, minutes left, and its…'
description: 'For a job a tool started (a list by reference bigger than one call): its status (queued, running, done, failed), rows done of the total, about how many minutes are left, and when done its run_id (use it as source { run } in any tool, or from_run in render_map) and what was written to the sheet.
Use when:
- After any tool answers with a job_id (a list too big for one call)
Coverage: Jobs started by the same person; checking costs no calls.
Reference: https://get-instamaps.com/mcp-server/tools/get_job'
tags:
- Runs and jobs
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
job_id:
type: string
required:
- job_id
responses:
'200':
description: The answer.
headers:
X-Lookups-Used:
schema:
type: integer
description: Lookups this call cost.
X-Lookups-Remaining:
schema:
type: integer
description: Free lookups left today.
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The answer in one or two sentences.
additionalProperties: true
'400':
description: The request could not be answered; error says why.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'401':
description: No API key, or an unknown or revoked one.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'404':
description: No such endpoint.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'429':
description: Today's free lookups are used up (or the call needs more than are left), or too many requests a minute.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
/v1/write_to_sheet:
post:
operationId: write_to_sheet
summary: 'Put an earlier answer into a Google Sheet: new dated columns beside the rows it…'
description: 'Writes an earlier answer into a Google Sheet without overwriting anything. Give run_id (every answer has one) to write its rows as new dated columns beside the rows they came from (matched by id; a row that now holds a different place is skipped and named), or as a table in a new tab; give job_id (a background job) to write each chunk beside its rows as it finishes, or the whole run when it is done. Each write adds a line to an "InstaMaps runs" tab. The sheet must be shared with the InstaMaps service account as Editor; if it isn''t, the error names the address.
Use when:
- The user wants the results in their sheet, next to their rows
- A background job should fill the sheet as it goes (pass its job_id)
- An answer should be kept as a dated tab of its own
Not for:
- A file to download or attach: geocode_batch with format "csv"
- A map to share: render_map
Coverage: Google Sheets shared with the InstaMaps service account as Editor; rows are matched by id, and a row that now holds a different place is skipped and named.
Reference: https://get-instamaps.com/mcp-server/tools/write_to_sheet'
tags:
- Runs and jobs
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
run_id:
type: string
description: The run_id from an answer (run.run_id), or from get_job when a job is done.
job_id:
type: string
description: Or a background job's job_id.
sheet:
type: string
description: 'A Google Sheets link. Default: the sheet the rows came from.'
tab:
type: string
description: 'The tab. Default: the tab the rows came from.'
mode:
type: string
enum:
- beside
- new_tab
description: 'beside: new columns next to the rows they came from (the default when the run came from this tab). new_tab: the rows as a table in a new tab (the default for any other sheet).'
columns:
type: array
items:
type: string
description: 'Which of the answer''s fields to write, by name (e.g. "Latitude", "Confidence", "Nearest A&E", or geocode keys such as postcode or uprn). Default: the tool''s usual columns.'
example:
run_id: run_ae02fe5fb0d18808
mode: new_tab
columns:
- lat
- lng
- postcode
- council
- uprn
- confidence
responses:
'200':
description: 'The answer. For example: "Wrote 3 rows to "geocode_batch · 2026-10-13 17:36" (a new tab) in InstaMaps write_to_sheet test (landmarks), and a line in "InstaMaps runs"."'
headers:
X-Lookups-Used:
schema:
type: integer
description: Lookups this call cost.
X-Lookups-Remaining:
schema:
type: integer
description: Free lookups left today.
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The answer in one or two sentences.
additionalProperties: true
'400':
description: The request could not be answered; error says why.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'401':
description: No API key, or an unknown or revoked one.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'404':
description: No such endpoint.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'429':
description: Today's free lookups are used up (or the call needs more than are left), or too many requests a minute.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
components:
securitySchemes:
apiKey:
type: http
scheme: bearer
bearerFormat: im_live_…
description: 'Authorization: Bearer <your API key> (or X-API-Key). Keys are free: sign in with Google at /developers/portal.'
externalDocs:
description: Docs, pricing and examples
url: https://get-instamaps.com/developers