---
title: "Natural-language event search"
method: POST
path: "/v1/query"
tags: ["events"]
---

# Natural-language event search

`POST /v1/query`

## Request

- Base URL: `https://lumify.ai`
- URL: `https://lumify.ai/v1/query`
- Auth: HTTP bearer

Map a natural-language query to the same filters GET /v1/events accepts,
then run that exact list query — results are identical to, and as fresh
as, calling /v1/events directly. This is a small rule-based mapper, not an
LLM call — see the module-level `_parse_nl_query` docstring for exactly
what it recognizes.

Body: {"query": "live nfl games today", "limit": 25}
An explicit top-level "limit" overrides one parsed from the text. Costs 1
credit, same as GET /v1/events — interpreting the query text is free.

## Request body

- NLQueryRequest
  - `query` string, required: Free text, e.g. 'live nfl games today' or 'college basketball this week'.
  - `limit` integer, nullable: Overrides any limit parsed from the query text. Max 100.

## Response `200`

Events matching the parsed query, the interpreted filters, and their REST equivalent

- NLQueryResponse
  - `query` string, required: The original natural-language query text.
  - `interpreted` NLQueryFilters, required
    - `sport` string, nullable
    - `status` string, nullable
    - `date` string, nullable
    - `from` string, nullable
    - `to` string, nullable
    - `limit` integer, nullable
  - `unrecognized_terms` string[]: Query words that didn't map to a known filter.
  - `equivalent_request` string, required: The literal GET /v1/events request this query was translated to.
  - `events` EventSummary[]
    - `id` integer, required
    - `name` string, nullable
    - `sport` string, nullable
    - `league` string, nullable
    - `season_id` integer, nullable
    - `starts_at` string, nullable: ISO-8601 UTC start time.
    - `inprogress_since` string, nullable: ISO-8601 UTC timestamp of the first ingest that marked this event inprogress (first live tick). Null until then; stays set after final. Walkovers and events that never went live are usually null. Not the same as starts_at, which can be a session floor (especially tennis).
    - `status` string, nullable
    - `period` string, nullable
    - `clock` string, nullable
    - `venue` object, nullable
  - `total` integer
  - `next_after_id` integer, nullable

## Other responses

- `422`: Validation Error

---

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