AlmanacDocs
API referenceEvents

List events

Public keyset-paginated list of markets. Defaults to live (not-ended) markets ordered by endDate ASC, id ASC. The cursor is opaque; pass it back verbatim to fetch the next page.

GET/v1/events

Query Parameters

format?string

Response format. csv returns text/csv (one row per event, nested fields JSON-stringified) with the next cursor in the X-Next-Cursor header instead of the body. Defaults to json.

Value in

  • "json"
  • "csv"
resolvedSince?string

ISO-8601 instant; only resolutions at/after this time. Requires sortBy=resolvedAt (400 otherwise).

status?string

Resolution-status filter. resolved/voided lifts the default live-only filter (like includeEnded=1); combining status=resolved|voided with includeEnded=0 or hasResolution=0 is a 400.

Value in

  • "unresolved"
  • "resolved"
  • "voided"
sortBy?string

Sort key. endDate/startDate/resolvedAt sort ASC, volume/liquidity DESC; id ASC is the tiebreak. Defaults to endDate.

Value in

  • "endDate"
  • "startDate"
  • "volume"
  • "liquidity"
  • "resolvedAt"
max_price?number

Upper bound (0..1): every current outcome price must be <= this.

min_price?number

Lower bound (0..1): every current outcome price must be >= this.

volume?number

Minimum volumeUsd (>= bound).

liquidity?number

Minimum liquidityUsd (>= bound).

hasResolution?number

1 returns only resolved markets; 0 only unresolved. Omit for both.

Value in

  • 0
  • 1
q?string

Case-insensitive substring match across question and description.

tagId?number

Filter to markets carrying this tag id at admission.

source?string

Filter by event source, e.g. polymarket.

includeEnded?number

0 (default) returns live markets only; 1 also includes ended markets.

Value in

  • 0
  • 1
cursor?string

Opaque pagination cursor from a prior response's nextCursor. Pass verbatim.

limit?number

Page size, 1..200. Defaults to 50.

Response Body

curl -X GET "https://example.com/v1/events"
{  "items": [    {      "id": "string",      "source": "polymarket",      "sourceMarketId": "string",      "question": "string",      "description": "string",      "outcomes": [        {          "outcomeId": "string",          "name": "string"        }      ],      "endDate": "2019-08-24T14:15:22Z",      "startDate": "2019-08-24T14:15:22Z",      "tagsAtAdmission": [        0      ],      "liquidityUsd": 0,      "volumeUsd": 0,      "volumeRecentUsd": 0,      "currentLiquidityUsd": 0,      "currentVolumeUsd": 0,      "currentOutcomePrices": {        "property1": 0,        "property2": 0      },      "admittedAt": "2019-08-24T14:15:22Z",      "lastSeenAt": "2019-08-24T14:15:22Z",      "resolution": {        "resolvedAt": "2019-08-24T14:15:22Z",        "resolutionStatus": "unresolved",        "winningOutcomeId": "string",        "winningOutcomeName": "string",        "finalOutcomePrices": {          "property1": 0,          "property2": 0        }      },      "outcomePricesAtAdmission": {        "property1": 0,        "property2": 0      }    }  ],  "nextCursor": "string",  "meta": {    "computedAt": "2019-08-24T14:15:22Z",    "scorerVersion": "string"  }}

Get an event by id GET

Returns one market by primary id with its resolution if present; 404 otherwise.

Random live event GET

Returns one random market from the assignment-shaped live pool (24h–7d to end, outcome prices in the validator band, title does not contain denied substrings such as tweet). Handy for test/agent pipelines. Pass `seed` for deterministic selection. 404 when that pool is empty.