---
title: "List Countries"
method: GET
path: "/api/v1/countries"
tags: ["countries"]
---

# List Countries

`GET /api/v1/countries`

## Request

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

Use when an agent needs the list of country tags that markets have been tagged with. Returns the canonical country vocabulary with per-country market counts. Accepts the same filter params as `list_markets` (source, category, status, volume/probability ranges, search, …): the counts then reflect that filtered population, so this doubles as a facet endpoint. The country dimension itself is ignored when computing counts, so passing `country=` does not collapse the menu. Useful as the menu source for the `country=` filter on `list_events` / `list_markets` / `top_movers`.

## Query parameters

- `spread_min` number, nullable: Minimum bid-ask spread (0-1). Higher = less liquid.
- `spread_max` number, nullable: Maximum bid-ask spread (0-1). Lower = more liquid.
- `probability_min` number, nullable: Minimum probability (0-1). Filters to markets above this implied probability.
- `probability_max` number, nullable: Maximum probability (0-1).
- `prob_24h_change_min` number, nullable: Minimum 24h probability change (-1 to 1, signed). Use 0.15 for >=15pp positive moves.
- `prob_24h_change_max` number, nullable: Maximum 24h probability change (-1 to 1, signed).
- `volume_24h_change_min` number, nullable: Minimum 24h notional volume change (signed USD; e.g. 1000 means +$1k vs prior 24h).
- `volume_24h_change_max` number, nullable: Maximum 24h notional volume change (signed USD).
- `source` string, nullable: Source name(s); single value or comma-separated list. Allowed: polymarket, kalshi, manifold, myriad, limitless, predict, opinion, gemini.
- `active` boolean, nullable: Filter by `active` flag (true/false).
- `closed` boolean, nullable: Filter by `closed` flag (true/false). Open markets are `closed=false`.
- `volume_24hr_min` number, nullable: Minimum 24h notional volume (USD). Excludes low-activity markets.
- `volume_24hr_max` number, nullable: Maximum 24h notional volume (USD).
- `volume_min` number, nullable: Minimum cumulative volume (USD). Excludes low-activity markets across full history.
- `volume_max` number, nullable: Maximum cumulative volume (USD).
- `rank_min` number, nullable: Minimum rank score (numeric). Higher = more prominent.
- `rank_max` number, nullable: Maximum rank score (numeric).
- `ends_after` string, date-time, nullable: Filter to events whose end_date >= this ISO 8601 datetime (e.g. `2026-06-01T00:00:00Z`).
- `ends_before` string, date-time, nullable: Filter to events whose end_date <= this ISO 8601 datetime.
- `hide_ended` boolean: If true, hide markets/events whose end_date is in the past (end_date <= now()); rows with no end_date are kept.
- `created_after` string, date-time, nullable: Filter to rows whose created_at >= this ISO 8601 datetime (first appearance in pdata's database).
- `created_before` string, date-time, nullable: Filter to rows whose created_at <= this ISO 8601 datetime.
- `status` string, nullable: Comma-separated status list; any of {open, closing-soon, resolved}
- `search` string, nullable: Full-text search across title, description, slug. Case-insensitive substring match.
- `sort` string, nullable: Field name; prefix '-' for descending order (e.g. `-volume_24hr`). Common allowed values: `volume_24hr`, `normalized_vol_24hr`, `liquidity`, `end_date`, `closed_time`, `updated_at`. Markets endpoints additionally accept `probability`, `prob_24h_change`, `spread`. Invalid values return 400.
- `categories` string, nullable: Comma-separated category labels to include (OR)
- `categories_exclude` string, nullable: Comma-separated category labels to exclude
- `hide_price_derivatives` boolean: If true, exclude events with is_price_derivative=TRUE
- `include_uncategorized` boolean: If true, the include clause also matches rows whose categories array is empty/NULL or contains only labels outside the canonical set (synthetic 'Other' bucket).
- `countries` string, nullable: Comma-separated country names to include (OR). Full English names per the AI categorizer's prompt — e.g. 'United States', 'United Kingdom', 'European Union'. No allow-list — misspelled values silently yield zero matches.
- `countries_exclude` string, nullable: Comma-separated country names to exclude.
- `include_uncountried` boolean: If true, the include clause also matches rows whose countries array is empty/NULL — country-agnostic markets (synthetic 'No country' bucket).
- `country_match` string: How multiple `countries` combine: 'any' (default, OR — tagged with any selected country) or 'all' (AND — tagged with all of them, e.g. both Iran and Israel). Markets carry ≤3 country tags.

## Response `200`

Successful Response

- CountriesOut: Envelope for /api/v1/countries. Added in Spec 3 D1 to carry `_meta`. Pre-Spec-3 the endpoint returned a bare `list[CountryCount]`; agents that mandate "every API response carries `_meta`" need an envelope. The frontend unwraps `.items` in `lib/api/countries.ts` so existing component code continues to receive an array.
  - `items` CountryCount[], required
    - `name` string, required
    - `count` 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)