POST /v1/runs - Mireye Earth

When to use this

When you don’t want to hold the connection open. POST /v1/runs accepts a job, returns 202 with a run_id immediately, and executes in the background — you read its state whenever you like:

Poll: GET /v1/runs/{run_id} — status, progress, and (once terminal) the result. This is the source of truth.
Stream: GET /v1/runs/{run_id}/events — server-sent events; a status frame on every change and a terminal final frame carrying the full run. A convenience over polling, not a second contract.

One kind today: fetch_batch — the exact /v1/fetch/batch request, same validation, same limits, same result body. More kinds hang off this spine as they ship.

Submit

curl -s https://api.mireye.com/v1/runs \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "kind": "fetch_batch",
    "request": {
      "locations": [{"lat": 29.7604, "lng": -95.3698},
                    {"address": "350 5th Ave, New York, NY 10118"}],
      "fields": ["elevation", "coast_distance_m"]
    }
  }' | jq

{
  "run_id": "run_a1b2c3d4e5f6",
  "status": "queued",
  "poll": "/v1/runs/run_a1b2c3d4e5f6",
  "events": "/v1/runs/run_a1b2c3d4e5f6/events"
}

Caller mistakes fail at submit, not in the background. An unknown field name, a missing field selection, or an oversize batch raises the same error the synchronous endpoint would (400 fields_unknown, 422, …) on the POST itself — a run never exists only to fail on something validation could have caught.

Poll

curl -s https://api.mireye.com/v1/runs/run_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" | jq

{
  "run_id": "run_a1b2c3d4e5f6",
  "kind": "fetch_batch",
  "status": "running",
  "created_at": "2026-07-27T09:00:00+00:00",
  "updated_at": "2026-07-27T09:00:04+00:00",
  "expires_at": "2026-08-26T09:00:00+00:00",
  "progress": {"done": 1, "total": 2},
  "request": {"…": "as submitted"},
  "result": null,
  "error": null
}

status walks queued → running → done | failed. Once done, result carries exactly the body the synchronous endpoint would have returned. Once failed, error carries {error, message, retryable} — a run_interrupted failure (the worker restarted mid-run, e.g. during a deploy) is always retryable: resubmit the same request.

Stream

curl -sN https://api.mireye.com/v1/runs/run_a1b2c3d4e5f6/events \
  -H "Authorization: Bearer $MIREYE_API_TOKEN"

event: status
data: {"status": "running", "progress": {"done": 1, "total": 2}}

event: final
data: {"run_id": "run_a1b2c3d4e5f6", "status": "done", "result": {…}, …}

The stream ends at the final frame. A run that finished before you connected skips straight to final. Streams are capped at 15 minutes (events_timeout error frame) — past that, poll.

Artifacts: the result as a file

Once a run is done, download its result instead of parsing it:

curl -sOJ https://api.mireye.com/v1/runs/run_a1b2c3d4e5f6/artifacts/csv \
  -H "Authorization: Bearer $MIREYE_API_TOKEN"

/artifacts/csv — one row per location, index-aligned: identity columns (index, ok, lat, lng, source, error), one column per field carrying the value (empty when absent or failed), and a failed_fields column naming what to distrust. Spreadsheet-ready.
/artifacts/geojson — a FeatureCollection, one Point per location (GeoJSON [lng, lat] axis order), field values as properties. A failed location keeps its slot as a null-geometry feature, so the collection stays index-aligned too.

Artifacts are rendered on read from the stored result, never stored — so they exist exactly as long as the run does (30 days), and there is no second copy on its own retention clock. A run that is still queued/running returns 409 run_not_ready (retryable); a failed run returns 409 run_failed (resubmit). PDF is deliberately not offered here: branded report generation lives in the delivery tooling, not the serving API.

Ownership, retention, errors

A run belongs to the account that submitted it. Anyone else’s run_id — and any unknown id — reads as 404 run_not_found: a run id does not leak whether someone else’s job exists.
Runs expire 30 days after submission and then read as 404. This is the same clock as every other address-holding store: a fetch_batch request can contain street addresses, and the disclosed 30-day retention applies to run documents too.
A batch location’s failure is inside the result (ok: false entries), exactly as on the synchronous endpoint — a failed location never fails the run.

​When to use this

​Submit

​Poll

​Stream

​Artifacts: the result as a file

​Ownership, retention, errors