predictionMarkets

At least for the time being, this endpoint requires a Growth or Enterprise plan. Learn more.

This endpoint requires a Growth or Enterprise plan. Learn more.

Returns

[PredictionMarket!]!

See PredictionMarket

Show Properties

String!

The unique identifier.

PredictionProtocol!

The prediction protocol. See PredictionProtocol

String!

The venue-specific market ID.

String

The venue-specific market slug.

String

The ID of the prediction event.

String

The venue-specific event ID.

String

The question or title.

String

The display label.

String

A clean, UI-ready label derived from label/question with the parent event name stripped (and Kalshi Yes:/No: prefixes unwrapped). Falls back to question when label is missing or unknown.

String

The parent event label.

String

Primary rules text.

String

Secondary rules text.

[String!]!

Venue-specific outcome IDs.

[String!]!

Internal outcome IDs.

[String!]

Labels for each outcome.

PredictionResolution

The resolution details. See PredictionResolution

String

URL of the large image.

String

URL of the thumbnail image.

String

URL of the small image.

Int

The creation timestamp.

Int

The last update timestamp.

Int

The timestamp when this entity opens.

Int

The timestamp when this entity closes.

Int

The expected resolution timestamp.

Int

The actual resolution timestamp.

Int!

The last observation timestamp.

Int

The network ID.

String

The exchange contract address.

[PredictionCategory!]

Categories associated with this entity. See PredictionCategory

String

The ID of the winning outcome.

PredictionMarketEnrichedMetadata

Per-domain structured enrichment (sports market type/teams/start times today). Null when no domain-specific signal extracted. See PredictionMarketEnrichedMetadata

Arguments

PredictionMarketsInput!

required

Input parameters containing market IDs to fetch. See PredictionMarketsInput

Show Properties

[String!]!

required

Associated market IDs.

Query Example

Test this query in the Explorer → Fetch a single prediction market by its ID to get comprehensive market details including outcomes, categories, resolution status, and timestamps.

{
  predictionMarkets(input: {
    marketIds: ["0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137"]
  }) {
    id
    question
    label
    rules
    outcomeLabels
    outcomeIds
    imageThumbUrl
    createdAt
    closesAt
    resolvesAt
    resolvedAt
    winningOutcomeId
    categories {
      name
      slug
      subcategories {
        name
        slug
			}
    }
    resolution {
      result
      source
    }
  }
}

Example Response

{
  "data": {
    "predictionMarkets": [
      {
        "id": "0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
        "question": "Will the Fed increase interest rates by 25+ bps after the March 2026 meeting?",
        "label": "25+ bps increase",
        "rules": "The FED interest rates are defined in this market by the upper bound of the target federal funds range. The decisions on the target federal fund range are made by the Federal Open Market Committee (FOMC) meetings.\n\nThis market will resolve to the amount of basis points the upper bound of the target federal funds rate is changed by versus the level it was prior to the Federal Reserve's March 2026 meeting.\n\nIf the target federal funds rate is changed to a level not expressed in the displayed options, the change will be rounded up to the nearest 25 and will resolve to the relevant bracket. (e.g. if there's a cut/increase of 12.5 bps it will be considered to be 25 bps)\n\nThe resolution source for this market is the FOMC’s statement after its meeting scheduled for March 17 - 18, 2026 according to the official calendar: https://www.federalreserve.gov/monetarypolicy/fomccalendars.htm.\n\nThe level and change of the target federal funds rate is also published at the official website of the Federal Reserve at https://www.federalreserve.gov/monetarypolicy/openmarket.htm.\n\nThis market may resolve as soon as the FOMC’s statement for their March meeting with relevant data is issued. If no statement is released by the end date of the next scheduled meeting, this market will resolve to the \"No change\" bracket.",
        "outcomeLabels": [
          "Yes",
          "No"
        ],
        "outcomeIds": [
          "54073086346734626735797775941991553522163760164405051969883391401961188364109:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137",
          "111080671036126109659854287535401661966194360665829017654832975124868412594547:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137"
        ],
        "imageThumbUrl": "https://polymarket-upload.s3.us-east-2.amazonaws.com/jerome+powell+glasses1.png",
        "createdAt": 1761685086,
        "closesAt": 1773792000,
        "resolvesAt": 1773792000,
        "resolvedAt": null,
        "winningOutcomeId": null,
        "categories": [
          {
            "name": "Economy",
            "slug": "economy",
            "subcategories": [
              {
                "name": "Fed",
                "slug": "fed"
              }
            ]
          },
          {
            "name": "Finance",
            "slug": "finance",
            "subcategories": []
          },
          {
            "name": "Politics",
            "slug": "politics",
            "subcategories": []
          },
          {
            "name": "Sports",
            "slug": "sports",
            "subcategories": []
          }
        ],
        "resolution": null,
        "networkId": 137,
        "exchangeAddress": "0xc5d563a36ae78145c45a50134d48a1215220f80a"
      }
    ]
  }
}

Usage Guidelines

Market ID Format

Market IDs follow platform-specific formats:

Polymarket: <marketAddress>:Polymarket:<exchangeAddress>:<networkId> (e.g., 0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38:Polymarket:0xc5d563a36ae78145c45a50134d48a1215220f80a:137)
Kalshi: <marketSlug>:Kalshi (e.g., KXMVECROSSCATEGORY-S2026A4A05B370DF-F1FBA451AA9:Kalshi)

These composite IDs uniquely identify a market across protocols and networks.

Batch Queries

You can query up to multiple markets in a single request by providing an array of marketIds. This is more efficient than making individual requests for each market. Consider batching when:

Displaying multiple markets on a single page
Comparing related markets
Building dashboards or aggregated views

Timestamps

All timestamp fields are returned as Unix timestamps (seconds since epoch). Note:

closesAt: When the market stops accepting new positions
resolvesAt: Expected resolution time (may differ from actual)
resolvedAt: Actual resolution time (null if unresolved)

Troubleshooting

Why am I getting 'null' for some fields?

Not all fields are available for every market or protocol. Different prediction protocols provide different levels of detail. Common null fields include:

venueMarketSlug: Some markets don’t have slugs
eventId, venueEventId: Only present for markets that are part of a larger event
rules2: Secondary rules are optional
imageLargeUrl, imageThumbUrl, imageSmallUrl: Images are not required
resolution: Only populated after market resolution

Always handle null values gracefully in your application code.

Market IDs not returning results

If your query returns an empty array or no results:

Verify the market ID format is correct for the platform:
- Polymarket: <marketAddress>:Polymarket:<exchangeAddress>:<networkId>
- Kalshi: <marketSlug>:Kalshi
Ensure the market exists on the specified protocol (POLYMARKET or KALSHI)
Check that you’re using the complete Codex market ID, not just the address portion
The market may have been delisted or removed from the platform
Try querying a known valid market ID to verify your API connection

Timestamps are showing incorrect dates

Timestamps are returned as Unix timestamps (seconds since epoch). Common issues:

JavaScript: Use new Date(timestamp * 1000) - multiply by 1000 to convert to milliseconds
Python: Use datetime.fromtimestamp(timestamp)
Timezone: Timestamps are in UTC; convert to your local timezone for display

If a timestamp is null, the event hasn’t occurred yet or the data isn’t available.

Categories or subcategories are empty

Not all markets are categorized. Categories are provided by the prediction protocol and may not be comprehensive. If categories is null or empty:

The market hasn’t been assigned to a category yet
The protocol doesn’t use categories for this market
Categories may be updated over time as markets are reclassified

Don’t rely solely on categories for filtering; consider using question text or labels instead.

Protocol field shows POLYMARKET but I expected KALSHI

Each market belongs to a specific protocol:

Market IDs are protocol-specific and cannot be used interchangeably
Verify you’re querying the correct market ID for your intended protocol
The protocol field indicates the source platform, not your preference

Getting authentication or permission errors

Prediction market data requires a Growth or Enterprise plan:

Verify your API key is valid and has the correct permissions
Check your plan tier at dashboard.codex.io/dashboard/billing
Ensure you’re including the Authorization header in your request
Contact support if you believe you should have access

API Documentation

Queries

Mutations

Subscriptions

Types

predictionMarkets

Returns

Arguments

Query Example

Usage Guidelines

Market ID Format

Batch Queries

Timestamps

Troubleshooting

​Returns

​Arguments

​Query Example

​Usage Guidelines

​Market ID Format

​Batch Queries

​Timestamps

​Troubleshooting

Returns

Arguments

Query Example

Usage Guidelines

Market ID Format

Batch Queries

Timestamps

Troubleshooting