---
title: "Natural-language Q&A over a US coordinate (LLM-backed)"
method: POST
path: "/v1/ask"
---

# Natural-language Q&A over a US coordinate (LLM-backed)

`POST /v1/ask`

## Request

- Base URL: `https://api.mireye.com`
- URL: `https://api.mireye.com/v1/ask`
- Auth: none declared
- TypeScript: <https://skmtc.dev/mireye/apis/mireye-earth/docs/v1/ask/post.ts> (a function with typed inputs; its response is checked against the schema)

Plans which catalog fields to fetch, fetches them, and synthesizes a cited answer. Much slower than `/v1/fetch`: typically ~6-20 s, hard-bounded at 110 s (then a `504 ask_timeout`). **Set a client timeout of at least 120 s.** For progressive output (first tokens ~5-7 s) use `POST /v1/ask/stream`. Returns `429 ask_busy` when the fleet-wide concurrency cap is saturated; retryable failures carry a `Retry-After` header.

## Headers

- `Idempotency-Key` string, nullable

## Request body

- AskRequest
  - `address` string, nullable
  - `include_trace` boolean
  - `lat` number, nullable
  - `lng` number, nullable
  - `max_cost_usd` string, nullable
  - `question` string, required

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mireye/apis/mireye-earth.md) - [All operations](https://skmtc.dev/mireye/apis/mireye-earth/llms.txt) - [OpenAPI document](https://skmtc.dev/mireye/apis/mireye-earth/revisions/d8410ba83654?raw)