POST

/api/v1/x/search

Adaptive, high-reasoning Grok 4.5 research over X

Research X with a high-reasoning xAI Grok 4.5 agent that runs multiple targeted searches, inspects the evidence, and refines or broadens later searches within a hard three-turn ceiling. The default and maximum window is 365 days. Results may include substantive original posts, replies, quote posts, and thread entries; only content-free promotion/spam, engagement bait, duplicates, and broad-topic matches without evidentiary value are excluded. The response returns citation-grounded posts, accounts, optional Quotient market context, and Quotient expert metadata. Results are not persisted by Quotient and provider storage is disabled. A request whose X Search does not execute or does not complete the required multi-search research returns 502 upstream_search_unavailable; candidate posts that all fail citation grounding return 502 upstream_grounding_failed. These failures are not billed. A 200 with meta.result_count 0 therefore means the search ran and genuinely found no candidate posts.

Price $1.00Auth x-quotient-api-key or x402Limit 5/s · 60/min · 500/day

Parameters

None.

Request body

application/json, required

Field	Type	Description
query required	string	Minimum length: 1; Maximum length: 4000
market_slugs	string[]	Optional cached Quotient markets to pair with X results. Maximum items: 10
from_date	string	Inclusive YYYY-MM-DD. Defaults to 365 days before to_date; the maximum span is 365 days. Format: date
to_date	string	Inclusive YYYY-MM-DD. Defaults to today; from_date still must be no more than 365 days earlier. Format: date
allowed_x_handles	string[]	Optional provider-enforced account allowlist. Maximum items: 20
limit	integer	Default: 8; Minimum: 1; Maximum: 15

Responses

200: Structured, citation-grounded X results

Field

Type

Description

query

string

summary

string

posts

XSearchPost[]

posts fields

Field

Type

Description

post_id

string

url

string

Format: uri

author_handle

string

author_name

string | null

published_at

string | null

Format: date-time

text

string

relevant_excerpt

string

relevance

string

stance

"supports_yes" | "supports_no" | "mixed" | "context" | "unknown"

linked_market_slugs

string[]

author_metadata

QuotientXAccountMetadata

Quotient's account classification metadata. Reviewed expert status records Quotient classification provenance.

author_metadata fields

Field

Type

Description

handle

string

display_name

string | null

x_user_id

string | null

current_username

string | null

is_quotient_expert

boolean

quotient_expert

object | null

quotient_expert fields

Field	Type	Description
designation	"reviewed_expert"
policy_version	string \| null

accounts

object[]

accounts fields

Field

Type

Description

handle

string

display_name

string | null

description

string | null

profile_url

string

quotient_metadata

QuotientXAccountMetadata

Quotient's account classification metadata. Reviewed expert status records Quotient classification provenance.

quotient_metadata fields

Field

Type

Description

handle

string

display_name

string | null

x_user_id

string | null

current_username

string | null

is_quotient_expert

boolean

quotient_expert

object | null

quotient_expert fields

Field	Type	Description
designation	"reviewed_expert"
policy_version	string \| null

quotient_markets

QuotientMarketContext[]

quotient_markets fields

Field

Type

Description

venue

required

"polymarket" | "polymarket_us" | "kalshi" | "limitless"

Prediction-market venue key: polymarket (Polymarket International), polymarket_us (Polymarket US), kalshi, or limitless.

nativeMarketId

required

string

nativeEventId

required

string | null

seriesTicker

required

string | null

marketKey

required

string

quotientMarketId

required

string

Stable Quotient market-page id: bare numeric for legacy Polymarket rows, venue-prefixed (kalshi:TICKER, polymarket_us:123, …) elsewhere. quotientUrl is exactly https://quotient.social/markets/{quotientMarketId} (URL-encoded) — the id form the market page resolves for every venue. A market with no Quotient coverage yet may not have a page.

slug

required

string | null

marketUrl

required

string | null

Connector-owned market page URL; null when unavailable.

Format: uri

sourceUrl

required

string | null

Connector provenance or API source URL.

Format: uri

broker_channels

required

"robinhood"[]

Retail brokers that carry this exact venue contract (same order book, same settlement). A broker distributes the venue contract; venue and marketKey remain the contract's identity. Today only robinhood, stamped on Kalshi rows from Robinhood's public listings; empty when no broker lists the market. Filter with topic=robinhood on /markets, /markets/mispriced and /signals, or tag=robinhood on /markets/search.

robinhood_category

required

string | null

Robinhood's own category slug for the listing (economics, politics, crypto, climate, …); null when not listed on Robinhood.

robinhood_url

required

string | null

Deep link to the Robinhood event page; null when not listed on Robinhood.

Format: uri

market_id

string | null

question

string

resolution_criteria

string | null

resolution_source

string | null

end_date

string | null

Format: date-time

condition_id

string | null

status

"open" | "resolved"

resolved_yes

boolean | null

venue_data

object

venue_data fields

Field	Type	Description
yes_odds	number \| null
volume_24h	number \| null

quotient_url

string | null

forecast

CompactForecast | null

forecast fields

Field

Type

Description

venue

required

"polymarket" | "polymarket_us" | "kalshi" | "limitless" | null

Prediction-market venue key: polymarket (Polymarket International), polymarket_us (Polymarket US), kalshi, or limitless.

market

required

CanonicalMarketRouting | null

market fields

Field	Type	Description
venue required	"polymarket" \| "polymarket_us" \| "kalshi" \| "limitless"	Prediction-market venue key: polymarket (Polymarket International), polymarket_us (Polymarket US), kalshi, or limitless.
nativeMarketId required	string
nativeEventId required	string \| null
seriesTicker required	string \| null
marketKey required	string
quotientMarketId required	string	Stable Quotient market-page id: bare numeric for legacy Polymarket rows, venue-prefixed (kalshi:TICKER, polymarket_us:123, …) elsewhere. quotientUrl is exactly https://quotient.social/markets/{quotientMarketId} (URL-encoded) — the id form the market page resolves for every venue. A market with no Quotient coverage yet may not have a page.
slug required	string \| null
marketUrl required	string \| null	Connector-owned market page URL; null when unavailable. Format: uri
sourceUrl required	string \| null	Connector provenance or API source URL. Format: uri
broker_channels required	"robinhood"[]	Retail brokers that carry this exact venue contract (same order book, same settlement). A broker distributes the venue contract; venue and marketKey remain the contract's identity. Today only robinhood, stamped on Kalshi rows from Robinhood's public listings; empty when no broker lists the market. Filter with topic=robinhood on /markets, /markets/mispriced and /signals, or tag=robinhood on /markets/search.
robinhood_category required	string \| null	Robinhood's own category slug for the listing (economics, politics, crypto, climate, …); null when not listed on Robinhood.
robinhood_url required	string \| null	Deep link to the Robinhood event page; null when not listed on Robinhood. Format: uri

required

string

probability

required

number

created_at

required

string

Format: date-time

headline

string | null

thesis

required

string | null

resolution_pathway

required

ResolutionPathway

The market contract and forecast crux needed to review how this forecast can resolve.

resolution_pathway fields

Field	Type	Description
criteria required	string \| null
crux required	string \| null
deadline required	string \| null	Format: date-time
source required	string \| null

delta_from_prior

number | null

delta_reasoning

string | null

refresh_reason

string | null

relationships

required

RelationshipsEnvelope

Bounded, non-recursive graph references. Each category publishes at most 50 lightweight refs. These refs contain no forecast probability, venue odds, aggregate asset probability, or inferred causal AFFECTS edge.

relationships fields

Field

Type

Description

assets

required

RelationshipAssetRef[]

Maximum items: 50

assets fields

Field	Type	Description
relationship required	"HAS_MARKET" \| "ON_MARKET" \| "ON_FORECAST" \| "HAS_SIGNAL"	Exact graph edge at the final hop. The API does not synthesize AFFECTS relationships.
direction required	"incoming" \| "outgoing"	Direction of the final graph edge relative to the response subject for direct refs, or relative to the explicit via node for two-hop refs.
via required	"direct" \| "market" \| "asset"	direct is one graph hop; market or asset names the explicit intermediate node for a bounded two-hop ref.
id required	string	Format: uuid
assetKey required	string
name required	string
ticker required	string \| null
asset_type required	string

markets

required

RelationshipMarketRef[]

Maximum items: 50

markets fields

Field	Type	Description
relationship required	"HAS_MARKET" \| "ON_MARKET" \| "ON_FORECAST" \| "HAS_SIGNAL"	Exact graph edge at the final hop. The API does not synthesize AFFECTS relationships.
direction required	"incoming" \| "outgoing"	Direction of the final graph edge relative to the response subject for direct refs, or relative to the explicit via node for two-hop refs.
via required	"direct" \| "market" \| "asset"	direct is one graph hop; market or asset names the explicit intermediate node for a bounded two-hop ref.
marketKey required	string
venue required	"polymarket" \| "polymarket_us" \| "kalshi" \| "limitless"	Prediction-market venue key: polymarket (Polymarket International), polymarket_us (Polymarket US), kalshi, or limitless.
nativeMarketId required	string
question required	string \| null

signals

required

RelationshipSignalRef[]

Maximum items: 50

signals fields

Field	Type	Description
relationship required	"HAS_MARKET" \| "ON_MARKET" \| "ON_FORECAST" \| "HAS_SIGNAL"	Exact graph edge at the final hop. The API does not synthesize AFFECTS relationships.
direction required	"incoming" \| "outgoing"	Direction of the final graph edge relative to the response subject for direct refs, or relative to the explicit via node for two-hop refs.
via required	"direct" \| "market" \| "asset"	direct is one graph hop; market or asset names the explicit intermediate node for a bounded two-hop ref.
id required	string
signal_type required	"prediction_market"
canonical_endpoint required	"/api/v1/signals"
side required	string \| null
published_at required	string \| null

truncated

required

object

truncated fields

Field	Type	Description
assets required	boolean
markets required	boolean
signals required	boolean

relationships

required

RelationshipsEnvelope

relationships fields

Field

Type

Description

assets

required

RelationshipAssetRef[]

Maximum items: 50

assets fields

Field	Type	Description
relationship required	"HAS_MARKET" \| "ON_MARKET" \| "ON_FORECAST" \| "HAS_SIGNAL"	Exact graph edge at the final hop. The API does not synthesize AFFECTS relationships.
direction required	"incoming" \| "outgoing"	Direction of the final graph edge relative to the response subject for direct refs, or relative to the explicit via node for two-hop refs.
via required	"direct" \| "market" \| "asset"	direct is one graph hop; market or asset names the explicit intermediate node for a bounded two-hop ref.
id required	string	Format: uuid
assetKey required	string
name required	string
ticker required	string \| null
asset_type required	string

markets

required

RelationshipMarketRef[]

Maximum items: 50

markets fields

Field	Type	Description
relationship required	"HAS_MARKET" \| "ON_MARKET" \| "ON_FORECAST" \| "HAS_SIGNAL"	Exact graph edge at the final hop. The API does not synthesize AFFECTS relationships.
direction required	"incoming" \| "outgoing"	Direction of the final graph edge relative to the response subject for direct refs, or relative to the explicit via node for two-hop refs.
via required	"direct" \| "market" \| "asset"	direct is one graph hop; market or asset names the explicit intermediate node for a bounded two-hop ref.
marketKey required	string
venue required	"polymarket" \| "polymarket_us" \| "kalshi" \| "limitless"	Prediction-market venue key: polymarket (Polymarket International), polymarket_us (Polymarket US), kalshi, or limitless.
nativeMarketId required	string
question required	string \| null

signals

required

RelationshipSignalRef[]

Maximum items: 50

signals fields

Field	Type	Description
relationship required	"HAS_MARKET" \| "ON_MARKET" \| "ON_FORECAST" \| "HAS_SIGNAL"	Exact graph edge at the final hop. The API does not synthesize AFFECTS relationships.
direction required	"incoming" \| "outgoing"	Direction of the final graph edge relative to the response subject for direct refs, or relative to the explicit via node for two-hop refs.
via required	"direct" \| "market" \| "asset"	direct is one graph hop; market or asset names the explicit intermediate node for a bounded two-hop ref.
id required	string
signal_type required	"prediction_market"
canonical_endpoint required	"/api/v1/signals"
side required	string \| null
published_at required	string \| null

truncated

required

object

truncated fields

Field	Type	Description
assets required	boolean
markets required	boolean
signals required	boolean

gaps

string[]

citations

string[]

meta

object

401: Unauthorized

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

402: Payment Required

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

403: Insufficient credits for the requested route

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

422: Invalid request body

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

429: The caller exceeded a per-second, per-minute, daily, or concurrency limit. No credits are debited and no x402 payment is settled for this response.

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

502: xAI unavailable (upstream_unavailable), X Search did not execute or complete the required multi-search research (upstream_search_unavailable), or candidate posts all failed citation grounding (upstream_grounding_failed). Not billed.

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

503: X search is not configured

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

Set QUOTIENT_API_KEY in your shell and replace example identifiers with returned IDs before running a request.

curl

curl --request POST \
  --header "x-quotient-api-key: $QUOTIENT_API_KEY" \
  --header "content-type: application/json" \
  --data '{"query":"What evidence is changing the odds of a 2026 Ukraine ceasefire?","market_slugs":["russia-x-ukraine-ceasefire-in-2026"],"limit":15}' \
  'https://quotient-api-gateway.onrender.com/api/v1/x/search'

200 · application/json

{
  "query": "example",
  "summary": "example",
  "posts": [
    {
      "post_id": "example",
      "url": "example",
      "author_handle": "example",
      "author_name": "example",
      "published_at": "2027-01-01T00:00:00Z",
      "text": "example",
      "relevant_excerpt": "example",
      "relevance": "example",
      "stance": "supports_yes",
      "linked_market_slugs": [
        "example"
      ],
      "author_metadata": {
        "handle": "example",
        "display_name": "example",
        "x_user_id": "example",
        "current_username": "example",
        "is_quotient_expert": false,
        "quotient_expert": {
          "designation": "reviewed_expert",
          "policy_version": "example"
        }
      }
    }
  ],
  "accounts": [
    {
      "handle": "example",
      "display_name": "example",
      "description": "example",
      "profile_url": "example",
      "quotient_metadata": {
        "handle": "example",
        "display_name": "example",
        "x_user_id": "example",
        "current_username": "example",
        "is_quotient_expert": false,
        "quotient_expert": {
          "designation": "reviewed_expert",
          "policy_version": "example"
        }
      }
    }
  ],
  "quotient_markets": [
    {
      "venue": "polymarket",
      "nativeMarketId": "example",
      "nativeEventId": "example",
      "seriesTicker": "example",
      "marketKey": "example",
      "quotientMarketId": "example",
      "slug": "example",
      "marketUrl": "example",
      "sourceUrl": "example",
      "broker_channels": [
        "robinhood"
      ],
      "robinhood_category": "example",
      "robinhood_url": "example",
      "market_id": "example",
      "question": "example",
      "resolution_criteria": "example",
      "resolution_source": "example",
      "end_date": "2027-01-01T00:00:00Z",
      "condition_id": "example",
      "status": "open",
      "resolved_yes": false,
      "venue_data": {
        "yes_odds": 0,
        "volume_24h": 0
      },
      "quotient_url": "example",
      "forecast": {
        "venue": "polymarket",
        "market": {
          "venue": "polymarket",
          "nativeMarketId": "example",
          "nativeEventId": "example",
          "seriesTicker": "example",
          "marketKey": "example",
          "quotientMarketId": "example",
          "slug": "example",
          "marketUrl": "example",
          "sourceUrl": "example",
          "broker_channels": [
            "robinhood"
          ],
          "robinhood_category": "example",
          "robinhood_url": "example"
        },
        "id": "example",
        "probability": 0,
        "created_at": "2027-01-01T00:00:00Z",
        "headline": "example",
        "thesis": "example",
        "resolution_pathway": {
          "criteria": "example",
          "crux": "example",
          "deadline": "2027-01-01T00:00:00Z",
          "source": "example"
        },
        "delta_from_prior": 0,
        "delta_reasoning": "example",
        "refresh_reason": "example",
        "relationships": {
          "assets": [
            {}
          ],
          "markets": [
            {}
          ],
          "signals": [
            {}
          ],
          "truncated": {
            "assets": false,
            "markets": false,
            "signals": false
          }
        }
      },
      "relationships": {
        "assets": [
          {
            "relationship": null,
            "direction": null,
            "via": null,
            "id": null,
            "assetKey": null,
            "name": null,
            "ticker": null,
            "asset_type": null
          }
        ],
        "markets": [
          {
            "relationship": null,
            "direction": null,
            "via": null,
            "marketKey": null,
            "venue": null,
            "nativeMarketId": null,
            "question": null
          }
        ],
        "signals": [
          {
            "relationship": null,
            "direction": null,
            "via": null,
            "id": null,
            "signal_type": null,
            "canonical_endpoint": null,
            "side": null,
            "published_at": null
          }
        ],
        "truncated": {
          "assets": false,
          "markets": false,
          "signals": false
        }
      }
    }
  ],
  "gaps": [
    "example"
  ],
  "citations": [
    "example"
  ],
  "meta": {}
}