List catalog-derived events for an exchange (router = all venues).

GET

/api/{exchange}/fetchEvents

const url = 'https://data.predictefy.com/api/example/fetchEvents?status=active&sort=volume&snapshotTTL=60000';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://data.predictefy.com/api/example/fetchEvents?status=active&sort=volume&snapshotTTL=60000' \
  --header 'Authorization: Bearer <token>'

Supported list params: status, sort, category, query, series, limit, offset, page, cursor, snapshotTTL. Cursor pagination freezes the catalog snapshot from page one. The four canonical taxonomy params are honored only when READS_ENABLE_TAXONOMY=true; while the flag is off they are accepted and ignored. The legacy searchIn param remains accepted and ignored.

Authorizations

bearerAuth

Parameters

Path Parameters

exchange

required

string

Query Parameters

status

string

default: active

Allowed values: active inactive closed resolved all

sort

string

default: volume

Allowed values: volume newest liquidity closeDate

category

string

categories

string

Comma-separated canonical category slugs (OR semantics, maximum 50). Unknown slugs match nothing. Honored only when READS_ENABLE_TAXONOMY=true; ignored while the flag is off.

excludeCategories

string

Comma-separated canonical category slugs to exclude (maximum 50). NULL/unclassified rows remain visible. Honored only when READS_ENABLE_TAXONOMY=true; ignored while the flag is off.

tags

string

Comma-separated canonical tag slugs (ANY-overlap semantics, maximum 50). Unknown slugs match nothing. Honored only when READS_ENABLE_TAXONOMY=true; ignored while the flag is off.

excludeTags

string

Comma-separated canonical tag slugs to exclude by overlap (maximum 50). Honored only when READS_ENABLE_TAXONOMY=true; ignored while the flag is off.

query

string

series

string

limit

integer

>= 1 <= 100

offset

integer

page

integer

>= 1

cursor

string

Opaque cursor returned by a prior page. Overrides offset/page and preserves the original catalog snapshot.

snapshotTTL

integer

default: 60000 <= 86400000

Cursor lifetime in milliseconds. 0 disables expiry for that cursor chain.

Responses

200

A page of events (BaseResponse + data + meta + page, like fetchMarkets).

application/json

object

success

required

boolean

data

required

Array<object>

object

required

string

title

required

string

description

required

string

slug

required

string

markets

required

Array<object>

object

marketId

required

string

title

required

string

description

required

string

outcomes

required

Array<object>

object

outcomeId

required

string

label

required

string

side

Stable binary side when asserted by the venue; omitted otherwise.

string

Allowed values: yes no

price

required

number | null

<= 1

priceUnavailable

boolean

priceBasis

What the numeric price represents at the venue.

venue-composite: Venue-provided composite price whose inputs are not decomposed here.
mid: Midpoint of the best bid and best ask.
ask: Best ask or equivalent venue buy price.
bid: Best bid or equivalent venue sell price.
last-trade: Most recent executed trade price.
amm-spot: Current AMM spot probability.
pool-share: Outcome pool divided by the total parimutuel pool.
odds-implied: Probability implied by venue odds.
complement: Synthesized as one minus the paired outcome price.

string

Allowed values: venue-composite mid ask bid last-trade amm-spot pool-share odds-implied complement

marketId

string

priceChange24h

number

metadata

object

key

additional properties

any

volume24h

required

Null means the venue publishes no such figure; 0 is a real venue-published zero

number | null

volume24hSource

Metric-specific provenance for volume24h. venue is published by the venue; derived_cumulative is Predictefy-derived from cumulative snapshots; derived_tape is Predictefy-derived from captured fills. A derived value must carry this field.

string

Allowed values: venue derived_cumulative derived_tape

liquidity

required

Null means the venue publishes no such figure; 0 is a real venue-published zero

number | null

url

required

string

eventId

string

slug

string

resolutionDate

string | null format: date-time

volume

number

openInterest

number

image

required

Known-absent is null; this key is always emitted for market records.

string | null

eventImage

required

Known-absent is null; event/parent artwork is distinct from market artwork.

string | null

category

string

tags

Array<string>

canonicalCategory

required

string | null

canonicalTags

required

Array<string>

tickSize

number

status

string

contractAddress

string

sourceMetadata

object

key

additional properties

any

sourceExchange

string

yes

object

outcomeId

required

string

label

required

string

side

Stable binary side when asserted by the venue; omitted otherwise.

string

Allowed values: yes no

price

required

number | null

<= 1

priceUnavailable

boolean

priceBasis

What the numeric price represents at the venue.

venue-composite: Venue-provided composite price whose inputs are not decomposed here.
mid: Midpoint of the best bid and best ask.
ask: Best ask or equivalent venue buy price.
bid: Best bid or equivalent venue sell price.
last-trade: Most recent executed trade price.
amm-spot: Current AMM spot probability.
pool-share: Outcome pool divided by the total parimutuel pool.
odds-implied: Probability implied by venue odds.
complement: Synthesized as one minus the paired outcome price.

string

Allowed values: venue-composite mid ask bid last-trade amm-spot pool-share odds-implied complement

marketId

string

priceChange24h

number

metadata

object

key

additional properties

any

object

outcomeId

required

string

label

required

string

side

Stable binary side when asserted by the venue; omitted otherwise.

string

Allowed values: yes no

price

required

number | null

<= 1

priceUnavailable

boolean

priceBasis

What the numeric price represents at the venue.

venue-composite: Venue-provided composite price whose inputs are not decomposed here.
mid: Midpoint of the best bid and best ask.
ask: Best ask or equivalent venue buy price.
bid: Best bid or equivalent venue sell price.
last-trade: Most recent executed trade price.
amm-spot: Current AMM spot probability.
pool-share: Outcome pool divided by the total parimutuel pool.
odds-implied: Probability implied by venue odds.
complement: Synthesized as one minus the paired outcome price.

string

Allowed values: venue-composite mid ask bid last-trade amm-spot pool-share odds-implied complement

marketId

string

priceChange24h

number

metadata

object

key

additional properties

any

object

outcomeId

required

string

label

required

string

side

Stable binary side when asserted by the venue; omitted otherwise.

string

Allowed values: yes no

price

required

number | null

<= 1

priceUnavailable

boolean

priceBasis

What the numeric price represents at the venue.

venue-composite: Venue-provided composite price whose inputs are not decomposed here.
mid: Midpoint of the best bid and best ask.
ask: Best ask or equivalent venue buy price.
bid: Best bid or equivalent venue sell price.
last-trade: Most recent executed trade price.
amm-spot: Current AMM spot probability.
pool-share: Outcome pool divided by the total parimutuel pool.
odds-implied: Probability implied by venue odds.
complement: Synthesized as one minus the paired outcome price.

string

Allowed values: venue-composite mid ask bid last-trade amm-spot pool-share odds-implied complement

marketId

string

priceChange24h

number

metadata

object

key

additional properties

any

down

object

outcomeId

required

string

label

required

string

side

Stable binary side when asserted by the venue; omitted otherwise.

string

Allowed values: yes no

price

required

number | null

<= 1

priceUnavailable

boolean

priceBasis

What the numeric price represents at the venue.

venue-composite: Venue-provided composite price whose inputs are not decomposed here.
mid: Midpoint of the best bid and best ask.
ask: Best ask or equivalent venue buy price.
bid: Best bid or equivalent venue sell price.
last-trade: Most recent executed trade price.
amm-spot: Current AMM spot probability.
pool-share: Outcome pool divided by the total parimutuel pool.
odds-implied: Probability implied by venue odds.
complement: Synthesized as one minus the paired outcome price.

string

Allowed values: venue-composite mid ask bid last-trade amm-spot pool-share odds-implied complement

marketId

string

priceChange24h

number

metadata

object

key

additional properties

any

asOf

required

string | null format: date-time

provenance

required

object

source

required

Venue-rest — per-request REST via the venue adapter (all 16 venues; the default stamp). predictefy-live — served from the live WebSocket hub or live order book; SX Bet overlay-bridge rows use this explicit source. fixture — offline sample data, never production venues. overlay — a serve-time catalog price overlay replaced the stored snapshot price for a fresh price-refresher entry.

string

Allowed values: venue-rest predictefy-live fixture overlay

capabilities

required

Market capability flags. history is true only when Predictefy’s history coverage for the venue is proven under docs/history-coverage.md; it is independent of venue-native history endpoints and the hosted fetchOHLCV route’s availability.

object

read

required

boolean

trade

required

boolean

depth

required

True when the venue exposes real order-book depth rather than an emulated or synthetic top-of-book (such as a single level synthesized from spot price, AMM pool, parimutuel odds, or P2P offer odds). Does not imply tradeable.

boolean

history

required

boolean

volume24h

required

Null means every member’s venue publishes no such figure; otherwise this is the sum of known member values

number | null

volume24hSource

object

sources

required

Array<string>

unique items

Allowed values: venue derived_cumulative derived_tape

partial

required

boolean

url

required

string

volume

number

image

string

category

string

tags

Array<string>

canonicalCategory

required

string | null

canonicalTags

required

Array<string>

sourceExchange

string

sourceMetadata

object

key

additional properties

any

asOf

string format: date-time

provenance

object

source

required

string

Allowed values: venue-rest predictefy-live fixture overlay

meta

required

object

asOf

required

string | null format: date-time

coverage

Present on archive-backed trade pages; earliest/latest archived trade for this outcome.

object

from

required

string format: date-time

required

string format: date-time

snapshot

object

version

required

string

loadedAt

required

string format: date-time

asOf

required

string | null format: date-time

totalsAsOf

Present when page.total came from the exact background totals matrix.

string format: date-time

totalUnavailable

Present if and only if page.total is null, explaining why the total is missing. Distinguishes “nothing matched” (total 0) from “your page was served but its matches were not counted” (total null).

string

provenance

required

object

source

required

string

Allowed values: venue-rest predictefy-live fixture overlay

page

required

object

limit

required

integer

offset

required

integer

total

required

Total matching rows, or null when the total was NOT computed — never a fabricated 0. The data page is the product and the count is metadata, so routes may warm an exact total off-request or abandon a count that exceeds its short budget while the page is still served. null is always accompanied by meta.totalUnavailable, which says why; use hasMore / nextCursor to walk the result set.

integer | null

hasMore

required

Whether another page exists. Determined by fetching one row beyond the requested limit, so it stays correct even when total is null.

boolean

nextCursor

Opaque cursor for the next page. Omitted on the final page.

string

nextCursor

string

Example

{
  "data": [
    {
      "markets": [
        {
          "outcomes": [
            {
              "side": "yes",
              "priceBasis": "venue-composite"
            }
          ],
          "volume24hSource": "venue",
          "yes": {
            "side": "yes",
            "priceBasis": "venue-composite"
          },
          "no": {
            "side": "yes",
            "priceBasis": "venue-composite"
          },
          "up": {
            "side": "yes",
            "priceBasis": "venue-composite"
          },
          "down": {
            "side": "yes",
            "priceBasis": "venue-composite"
          },
          "provenance": {
            "source": "venue-rest"
          }
        }
      ],
      "volume24hSource": {
        "sources": [
          "venue"
        ]
      },
      "provenance": {
        "source": "venue-rest"
      }
    }
  ],
  "meta": {
    "provenance": {
      "source": "venue-rest"
    }
  }
}

400

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

Allowed values: VALIDATION_ERROR NOT_SUPPORTED ACCOUNTS_UNSUPPORTED VENUE_NOT_AVAILABLE EXCHANGE_NOT_AVAILABLE MARKET_NOT_FOUND EVENT_NOT_FOUND CLUSTER_NOT_FOUND OUTCOME_NOT_FOUND SNAPSHOT_NOT_FOUND CATALOG_UNAVAILABLE CATALOG_QUERY_TOO_BROAD HISTORY_UNAVAILABLE ROUTE_NOT_FOUND INTERNAL AUTHENTICATION_ERROR PERMISSION_DENIED RATE_LIMIT_EXCEEDED NETWORK_ERROR NOT_FOUND BAD_REQUEST BRIDGE_UNSUPPORTED BRIDGE_UPSTREAM BRIDGE_PROVIDER_UNAVAILABLE BRIDGE_TRANSACTION_NOT_FOUND BRIDGE_SESSION_NOT_FOUND TRANSFER_PLAN_UNSUPPORTED UNAUTHORIZED SCOPE_MISSING PLAN_REQUIRED INSUFFICIENT_CREDITS RATE_LIMITED GEO_BLOCKED VENUE_REGION_BLOCKED IDEMPOTENCY_KEY_REQUIRED IDEMPOTENCY_CONFLICT ARTIFACT_VERSION_CONFLICT SPEND_CAP_EXCEEDED ARTIFACT_BOUNDS_VIOLATION ARTIFACT_INTEGRITY_MISMATCH VENUE_NOT_SUPPORTED EXECUTION_NOT_FOUND NOT_IMPLEMENTED VENUE_CREDENTIAL_REJECTED VENUE_CREDENTIAL_BREAKER_OPEN GEMINI_TIME_NONCE_REQUIRED GEMINI_HEARTBEAT_KEY_UNSUPPORTED VENUE_RELAY_FAILED EXEC_UNAVAILABLE RAIN_INVALID_OPTION RAIN_INVALID_SIDE RAIN_INVALID_PRICE RAIN_INVALID_AMOUNT RAIN_SLIPPAGE_REQUIRED RAIN_INVALID_DEADLINE RAIN_PHASE_NOT_OPEN RAIN_ORDER_LIMIT_REACHED RAIN_POOL_SAFETY_CHECK_FAILED PLATFORM_UNAVAILABLE PACK_NOT_FOUND BILLING_UNAVAILABLE BILLING_CUSTOMER_REQUIRED INVALID_SIGNATURE FEED_NOT_FOUND FEEDS_UNAVAILABLE FEED_UPSTREAM MATCHES_UNAVAILABLE

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

401

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

402

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

403

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

404

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}

429

Enveloped error.

application/json

object

success

required

boolean

error

required

object

message

required

string

code

required

string

retryable

required

boolean

requestId

required

Always present on errors; quote this id when reporting a failed request.

string

exchange

Present only when a venue error is attributed to a specific exchange.

string

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR"
  }
}