---
title: "Suggest"
method: GET
path: "/api/v1/search/suggest"
tags: ["search"]
---

# Suggest

`GET /api/v1/search/suggest`

## Request

- Base URL: `https://api.pdata.world`
- URL: `https://api.pdata.world/api/v1/search/suggest`
- Auth: none declared

Use when an agent has a name or phrase and needs the `(source, id)` of the matching event or market before calling another tool. Resolves free text against events AND markets in one call, best-first, and reports `total_events` / `total_markets` so the agent can tell a precise hit from an ambiguous one. Every row carries `event_path`, the internal link to use for follow-up lookups. Prefer this over running `list_events?search=` and `list_markets?search=` separately when the goal is identification rather than a filtered listing. Note: `headline` carries literal `<b>` highlight markup — quote `title` instead, or strip the tags.

## Query parameters

- `q` string, required: Free-text query, matched against event titles and market questions. Queries shorter than 2 characters deliberately return an empty result set rather than half the dataset.
- `limit` integer: Maximum number of coalesced results to return (1-20, default 8). `total_events` / `total_markets` in the envelope are uncapped and reflect the full match count, not this limit.

## Response `200`

Successful Response

- SearchSuggestOut: Envelope kept distinct from `Page` because suggest never paginates — `total` is meaningless when ranking truncates aggressively at 8. But we *do* expose total match counts so the frontend can render a "View all N results" deep-link footer (the typeahead becomes a launchpad to the markets page, not a dead-end at 8 hits).
  - `results` SearchHit[], required
    - `kind` 'event' | 'market', required
    - `id` string, required
    - `source` string, required
    - `title` string, required
    - `headline` string, nullable, required: `title` with the query's matched fragments wrapped in literal `<b>`/`</b>` tags (Postgres `ts_headline` output), for callers that render highlighted search rows. This is markup, not prose: non-rendering consumers — LLM agents especially — should quote `title` instead, or strip the tags before echoing this field. Null when the row was matched without highlighting.
    - `status` 'open' | 'closing-soon' | 'past' | 'resolved', required
    - `volume_24hr` number, nullable, required: Venue-reported 24h volume, in the venue's own unit (shares, contracts, mana); not converted between venues.
    - `volume` number, nullable, required: Venue-reported lifetime volume, in the venue's own unit (shares, contracts, mana); not converted between venues.
    - `child_count` integer, nullable, required: Number of child markets (events only); null for markets.
    - `url_path` string, nullable, required: The venue's own page for this row when known (https://…); otherwise, for events, the internal pdata path.
    - `event_path` string, nullable, required: Internal pdata.world path to the row's event page: `/events/{source}/{event_id}`, plus `#market={market_id}` for a market, which pre-selects it. Null for a market with no parent event.
    - `event_title` string, nullable, required
    - `probability` number, nullable, required
    - `prob_24h_change` number, nullable, required
    - `end_date` string, nullable, required
  - `total_events` integer, required
  - `total_markets` integer, required
  - `_meta` ResponseMetaList: Agent metadata for list/aggregate responses (no cite_as).
    - `attribution` string: Who aggregated this data, under which licence, and whose data it is.
    - `canonical_url` string, required: Stable URL for this resource: the pdata.world page, or the API URL for list responses.
    - `as_of` string, date-time: When this response was generated (UTC).
    - `docs` string: API documentation.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/pdata/apis/pdata-backend.md) · [All operations](https://skmtc.dev/pdata/apis/pdata-backend/llms.txt) · [OpenAPI document](https://skmtc.dev/pdata/apis/pdata-backend/revisions/4c9bf3856786?raw)