---
title: "Query intelligence"
method: POST
path: "/v1/query"
tags: ["Intelligence"]
---

# Query intelligence

`POST /v1/query`

## Request

- Base URL: `https://api.onegoodarea.com`
- URL: `https://api.onegoodarea.com/v1/query`
- Auth: one of:
  - HTTP bearer
  - none

Run a query plan or natural-language question against the intelligence moat. Supports rank_areas, get_area, score_area, compare_areas, find_peers, find_insights, and find_forecast. A rank_areas plan on a deprivation signal must set `country` or `lad` (deciles and ranks are relative within a nation), otherwise it is rejected with 422, code `invalid_signal`. Callable without an API key at the anonymous tier's quota (AR-594, Plan 059.2). Natural-language queries on free tiers (anonymous, logged_in, basic) are processed by OpenCode and OpenRouter free models, which may retain prompts for model improvement. Paid tiers and programmatic plan queries do not use these providers.

## Query parameters

- `bundle` string

## Request body

- union: Natural language question or a programmatic plan object.
  - object: Natural language question.
    - `question` string, required
  - object: Programmatic plan object.
    - `plan` object, required

## Response `200`

Default Response

- object
  - `plan` object, required
  - `plan_source` 'client' | 'nl', required
  - `results` union
    - object[]
    - object
  - `meta` object
    - `generated_at` string, required

## Other responses

- `400`: Default Response
- `404`: Default Response
- `422`: Default Response
- `429`: Default Response
- `500`: Default Response
- `502`: Default Response

## Changes

- **2026-10-20** `b318d28b3412`: 4 warning
  - added the new `nation_not_covered` enum value to the `anyOf[subschema #1]/code` response property for the response status `422`
  - added the new `nation_not_covered` enum value to the `anyOf[subschema #1]/reason` response property for the response status `422`
  - added the new `nation_not_covered` enum value to the `code` response property for the response status `502`
  - added the new `nation_not_covered` enum value to the `reason` response property for the response status `502`

[Operation history](https://skmtc.dev/onegoodarea/apis/onegoodarea-api/changes/v1/query/post.md)

---

[API](https://skmtc.dev/onegoodarea/apis/onegoodarea-api.md) · [All operations](https://skmtc.dev/onegoodarea/apis/onegoodarea-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onegoodarea/apis/onegoodarea-api/revisions/b318d28b3412?raw)