Mireye

/api-reference/runs

POST /v1/runs

cURL

curl --request POST \
  --url https://api.example.com/v1/runs \
  --header 'Content-Type: application/json' \
  --data '
{
  "kind": "<string>",
  "request": {
    "locations": [
      {
        "lat": 123,
        "lng": 123,
        "address": "<string>"
      }
    ],
    "fields": [
      "<string>"
    ]
  }
}
'

Submit a job, get a run_id immediately, poll or stream its progress.

cURL

curl --request POST \
  --url https://api.example.com/v1/runs \
  --header 'Content-Type: application/json' \
  --data '
{
  "kind": "<string>",
  "request": {
    "locations": [
      {
        "lat": 123,
        "lng": 123,
        "address": "<string>"
      }
    ],
    "fields": [
      "<string>"
    ]
  }
}
'

​ When to use this

  • 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.

​ 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

​ Poll

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

​ Stream

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

​ Artifacts: the result as a file

cURL
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.

​ 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.

N locations, one field selection.

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.

Show child attributes

Successful Response