Skip to content
Outcome
Open the app

Documentation

Market data,
in detail.

Query prediction market history with SQL. Explore the data, connect an agent, or bring a question into your own tools.

First query

Have a .edu email? Sign up with it to get $20 in free query credits. Follow the .edu credits guide to get started.

  1. 01Sign in at app.outcome.sh. Magic-link email, no password and no credit card.
  2. 02Create a key under API Keys in the dashboard. Keys are shown once.
  3. 03POST your SQL:
quickstart.sh
curl -X POST https://api.outcome.sh/v1/execute \
  -H "Authorization: Bearer $OUTCOME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT max(created_time) AS last_trade FROM trades"}'

Playground

The playground runs the same queries in the browser, with the live schema, charts, and an AI analyst. No key required.

MCP

Claude, Cursor, and other MCP clients can explore the schema and run queries through the MCP server.

$20 in free query credits for .edu signups

Sign up for Outcome with an email address ending in .edu to get $20 in free query credits, added automatically after you verify your email and create a workspace. Each user can receive the grant once. No payment card is required. Use the credits to explore prediction market history, test a research question, or build your first analysis.

  1. 01Open Outcome and sign up with your .edu email address.
  2. 02Open the sign-in link sent to that inbox to confirm your email, then create your workspace. Your workspace receives $20 (20,000 credits) automatically. Creating another workspace does not grant more credits.
  3. 03Continue through setup. The separate $5 offer for adding a payment card is optional; you can skip it and use your .edu credits immediately.
  4. 04Explore the playground or follow the first-query guide to query the data through the API.

Check your balance in Billing. See Credits and limits for how query usage is charged.

API keys

Query and MCP requests authenticate with an API key in the Authorization header. Keys are created and revoked in the dashboard, belong to your team, and spend the team credit balance when SQL executes. The same key works for the execute endpoint and the MCP server. Reading the public schema does not require a key.

header
Authorization: Bearer $OUTCOME_API_KEY
  • Each key allows 5 requests in a sliding one-second window, shared across all rate-limited endpoints using that key.
  • A leaked key can spend your credits. Revoke it from the API Keys page.
  • GET /v1/schema is public and needs no key.

Execute a query

POST/v1/execute

Runs a single read-only SQL statement against the warehouse and returns the rows as a JSON array. SELECT, WITH, EXPLAIN, and SHOW are permitted; anything that writes, touches system tables, or reaches external data is rejected before it runs.

Request body

querystringrequired

A single read-only SQL statement. JSON responses are capped at 10,000 rows and 8 MiB, with a 1 MiB limit per row. Execution is limited to 60 minutes; available credits can impose a shorter limit. SQL SETTINGS, FORMAT, and INTO clauses are rejected.

finalbooleanoptional

When true, applies the ClickHouse FINAL modifier so markets and trades return merged, deduplicated rows instead of occasional pre-merge duplicates. Slower and scans more; use it only when exact dedup matters.

Allow at least 61 minutes for client request timeouts so the server can return a result or timeout error after the full query window.

Example

request.sh
curl -X POST https://api.outcome.sh/v1/execute \
  -H "Authorization: Bearer $OUTCOME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT ticker, yes_price FROM markets ORDER BY volume_24h DESC LIMIT 5"}'
200 OK
[
  { "ticker": "KXMENWORLDCUP-26-ES", "yes_price": 0.999 },
  { "ticker": "KXTECHLAYOFFS-26", "yes_price": 0.911 },
  { "ticker": "KXUSAALIENS-27", "yes_price": 0.074 }
]

Usage headers

Every successful response reports what the query cost:

X-Credits-Usedintegeralways

Computed credit cost for this query. Present even if the subsequent charge fails; this header alone does not confirm a charge.

X-Duration-Msintegeralways

Wall-clock execution time in milliseconds.

X-Bytes-Readintegeralways

Bytes the warehouse scanned to answer the query.

X-Credits-Remainingintegerwhen charged

Team balance after a successful charge. Omitted when the charge did not succeed.

response headers
HTTP/2 200
X-Credits-Used: 2
X-Duration-Ms: 118
X-Bytes-Read: 204811520
X-Credits-Remaining: 49998

Streaming and exports

POST/v1/execute/streamPOST/v1/exports

Both endpoints accept the same query and optional final fields as /v1/execute and use the same authentication and query billing. They avoid the JSON endpoint’s 10,000-row and 8 MiB response limits. Individual rows still have a 1 MiB limit: return ordinary rows instead of collecting results into a large groupArray or JSON string. Query memory and time limits still apply.

Stream NDJSON

/v1/execute/stream sends one row record per line, followed by a completion record with the final row count, usage, and billing. Consume it incrementally. A 200 status alone does not mean the query succeeded: reject error records, missing or unsuccessful completion, row-count mismatches, and truncated transfers. Usage comes from the completion record, not response headers. Disconnecting cancels database consumption.

NDJSON response
{"type":"row","row":{"number":0}}
{"type":"complete","success":true,"row_count":1,"bytes_read":8,"duration_ms":12,"credits_used":1,"charged":true,"credits_remaining":99}

Create a downloadable export

POST /v1/exports runs the query and writes a file to private storage. Set format to csv for spreadsheets or ndjson for JSON Lines (the API default). An optional name uses your query title for the download filename, normalized with a UTC timestamp; new JSON Lines files use .jsonl. Keep the request open until it returns 201 with id, download_url, format, and completion. The file is published only after successful completion. JSON Lines includes the final completion record; CSV contains column headers and data rows, with completion and billing in the API response. Download directly from the signed URL; loading the file into a browser array or Blob defeats the memory benefit.

export.sh
curl --max-time 3660 https://api.outcome.sh/v1/exports \
  -H "Authorization: Bearer $OUTCOME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT number FROM numbers(20001)","format":"csv"}'

CSV preserves query-column order, quotes commas and newlines, represents null as an empty cell, and writes nested values as JSON text. Formula-like string cells are prefixed with an apostrophe for spreadsheets; use JSON Lines for exact original text. The table view keeps its 10,000-row cap; downloads bypass that cap.

POST/v1/exports/results

Save an existing JSON result array using its original response bytes as the body. Set ?format=csv or ?format=ndjson and an optional name. This stores the supplied data without running SQL or charging credits, and adds the file to Exports. The response uses the same completion contract with zero credits used. Uploads are limited to 10,000 rows, 8 MiB total, 1 MiB per row, and two minutes. CSV columns follow sorted JSON keys. The playground reuses only complete results matching the exact SQL and account; older results without that metadata cannot be reused safely. An upload failure never automatically starts a new query.

GET/v1/exports

List your team’s completed files, including older exports and files whose creation response was interrupted. Each page contains up to 100 exports with id, format, filename, size_bytes, created_at, and expires_at. Pass the returned cursor as ?cursor=... to continue in storage-key order. The Exports page under Workspace and in the profile menu uses this endpoint.

GET/v1/exports/{id}

Save the export ID. An authenticated GET returns a fresh download_url for a completed export owned by your team without rerunning or rebilling the query. Links last up to one hour and files are retained for seven days. Signed links grant access to the file; share them only with intended recipients.

If creation fails after returning X-Export-ID, check that ID before submitting another POST: the file may already be complete and the query billed. A lost connection before headers may leave the outcome unknown. Creating another export always starts a new query. A 404 lookup means no completed export is available to your team; a 503 can mean capacity is busy or exports are not configured. Cancellation requests stop ongoing work, but cannot undo a completed query or charge.

The live schema

GET/v1/schema

Returns every queryable table with its columns and exact ClickHouse types. Public, no key required. Feed it to a code generator or an agent before it writes SQL.

request.sh
curl https://api.outcome.sh/v1/schema
200 OK
{
  "tables": [
    {
      "name": "markets",
      "columns": [
        { "name": "venue", "type": "LowCardinality(String)" },
        { "name": "ticker", "type": "String" },
        { "name": "yes_price", "type": "Float64" },
        ...
      ]
    },
    ...
  ]
}

The tables

Keep venue and ticker together as the market identifier in your queries. Coverage varies by venue, market, date, and dataset; inspect actual observations for the period you intend to study.

Use Outcome for analytical research. Check the latest available timestamps, missing periods, and contract rules before interpreting results. A last-trade timestamp can reflect market inactivity as well as collection gaps, and a notebook update time does not establish the freshness of its cached query results.

Types below are simplified. For exact ClickHouse types, use GET /v1/schema.

market_metadata

Market identifiers, titles, status, contract rules, and settlement metadata. Use venue and ticker together to identify a contract; inspect nullable fields before relying on a value.

market_metadata.sql
-- Inspect contract rules and resolution sources
SELECT venue, ticker, title, rules_primary, resolution_source
FROM market_metadata
WHERE is_deleted = 0
LIMIT 10
columns
  • venuetext
  • is_deleteduint8
  • tickertext
  • titletext
  • statustext
  • close_timetimestamp
  • event_tickertext
  • open_timetimestamp
  • created_timetimestamp
  • expiration_timetimestamp
  • expected_expiration_timetimestamp
  • market_typetext
  • strike_typetext
  • resulttext
  • rules_primarytext
  • rules_secondarytext
  • notional_valuetext
  • yes_sub_titletext
  • no_sub_titletext
  • updated_timetimestamp
  • condition_idtext
  • yes_token_idtext
  • no_token_idtext
  • yes_payouttext
  • no_payouttext
  • resolution_sourcetext
  • settled_timetimestamp

markets

The latest stored market state, including title, status, prices, volume, liquidity fields, and contract rules. Inspect updated_time and the source contract before interpreting a price.

markets.sql
-- Inspect recent stored market state
SELECT venue, ticker, title, yes_price, updated_time
FROM markets
WHERE is_deleted = 0
ORDER BY volume_24h DESC
LIMIT 5
columns
  • venuetext
  • tickertext
  • event_tickertext
  • titletext
  • yes_sub_titletext
  • no_sub_titletext
  • statustext
  • resulttext
  • market_typetext
  • strike_typetext
  • yes_pricefloat
  • no_pricefloat
  • yes_bidtext
  • yes_asktext
  • no_bidtext
  • no_asktext
  • volumefloat
  • volume_24hfloat
  • liquiditytext
  • yes_liquidityfloat
  • no_liquidityfloat
  • notional_valuetext
  • rules_primarytext
  • rules_secondarytext
  • open_timetimestamp
  • created_timetimestamp
  • close_timetimestamp
  • expiration_timetimestamp
  • expected_expiration_timetimestamp
  • updated_timetimestamp
  • is_deleteduint8
  • condition_idtext
  • yes_token_idtext
  • no_token_idtext
  • yes_payouttext
  • no_payouttext
  • resolution_sourcetext
  • settled_timetimestamp

trades

Stored transaction observations with timestamps, YES and NO prices, and contract counts. Check the available dates and gaps for each venue and ticker before treating a result as a complete history.

trades.sql
-- Inspect observations for one market
SELECT venue, ticker, created_time, yes_price, count
FROM trades
WHERE venue = 'YOUR_VENUE'
  AND ticker = 'YOUR_TICKER'
  AND is_deleted = 0
ORDER BY created_time DESC, trade_id DESC
LIMIT 100
columns
  • venuetext
  • trade_idtext
  • tickertext
  • yes_pricefloat
  • no_pricefloat
  • countfloat
  • taker_sidetext
  • taker_book_sidetext
  • taker_outcome_sidetext
  • created_timetimestamp
  • is_deleteduint8
  • condition_idtext
  • token_idtext
  • outcome_labeltext

resolved_markets

Available settled-market result labels. Inspect the actual labels and contract rules before mapping results to binary outcomes; nullable and non-binary values need explicit treatment.

resolved_markets.sql
-- Inspect available resolution labels by venue
SELECT venue, result, count() AS markets
FROM resolved_markets
GROUP BY venue, result
columns
  • venuetext
  • tickertext
  • resulttext

The MCP server

POST/v1/mcp

A remote MCP server for Claude, Cursor, and any other MCP client: the agent discovers the schema, queries the market, and creates or edits your saved queries and notebooks. Streamable HTTP (protocol 2025-06-18), authenticated with your API key. SQL execution uses the same read-only rules, rate limits, and billing as the execute endpoint. Document edits do not execute SQL. Nothing to install or host.

Connect a client

terminal
claude mcp add --transport http outcome https://api.outcome.sh/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Tools

list_tablesfree

List every public table with its columns and types. Takes no arguments.

describe_tablefree

Return the schema of a single table by name.

preview_tablebilled

Fetch a bounded sample of rows (up to 100) from one table, optionally restricted to specific columns. The server generates the SQL; no arbitrary queries.

run_querybilled

Execute a read-only SQL query with exactly the same rules, limits, and billing as POST /v1/execute. Returns rows plus row count, bytes read, credits used, and duration.

list_saved_queriesfree

List your saved SQL queries, including their IDs, names, SQL, and saved chart layouts. Takes no arguments.

get_saved_queryfree

Read one of your saved queries by id, including its saved chart layouts.

create_saved_queryfree

Save a new query with a required name and query (SQL text). Does not execute SQL.

update_saved_queryfree

Update a saved query by id. Supply name, query, or both; omitted fields are preserved. Does not execute SQL.

delete_saved_queryfree

Delete one of your saved queries by id. Existing notebook references will need to be removed or replaced.

list_workspacesfree

List your notebooks, newest updated first, by filtering kind to notebook.

get_workspacefree

Read a notebook by id, including every ordered block and its current version.

create_workspacefree

Create a notebook with kind set to notebook and a required name. Optionally supply description, refresh_mode, refresh_interval_seconds, and blocks. Defaults to manual refresh and no blocks.

update_workspacefree

Update a workspace using id and its current version. Supply name, description, refresh_mode, refresh_interval_seconds, or blocks. Omitted fields stay unchanged; supplied blocks replace the entire block array.

delete_workspacefree

Delete a notebook using id and its current version. Saved queries and their cached results are retained.

A typical session: list_tables once, a preview or two, then run_query. Billed tools report credits used in their results. Saved-query and workspace tools operate only on documents owned by the authenticated user.

Create notebooks

Notebooks appear in the app sidebar. Use list_saved_queries or get_saved_query to find the actual query ID and its charts[].id values, or create_saved_query to save new SQL first. Query blocks accept a display of chart, table, or number. Omit chart_id for an automatic chart; supply an existing chart ID to reuse that query’s saved layout. Give each block a unique, stable ID.

In the app, notebooks combine text and query cells in a single document. Cell settings show a live preview beside the query and chart controls on desktop, or above them on mobile. The save status and actions stay visible in the settings footer.

Choose a saved query to preview its cached result. Changing the cell title, chart layout, or Chart/Value/Table display updates the preview immediately without running SQL. Visualization shows the chosen display; Data shows the same result as a table without changing the cell’s saved display. Refresh runs the current saved query using normal query credits. If no cached result exists, use Run query to load one. Saving cell settings does not execute SQL.

create-notebook.json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_workspace",
    "arguments": {
      "kind": "notebook",
      "name": "Volume investigation",
      "blocks": [
        {
          "id": "research-intro",
          "type": "markdown",
          "content": "# Volume investigation\n\n- Compare activity across venues.\n- Record unusual changes."
        },
        {
          "id": "research-results",
          "type": "query",
          "query_id": "YOUR_SAVED_QUERY_ID",
          "display": "table"
        }
      ]
    }
  }
}

Edit without losing content. Read the latest workspace before editing or deleting. Updates and deletions require its positive version number. If another edit causes a version conflict, read again and merge your intended changes with the current document before retrying. Supplying blocks replaces every block: retain unchanged blocks and their IDs, then send the complete ordered array. An empty array clears all blocks. Omit unchanged fields instead of sending null. Use an empty description string to clear the description.

Preserve rich notebook text. New text can use Markdown, as shown above. Existing notebook text may have content_format set to tiptap and content containing serialized JSON. Preserve both fields on unchanged blocks. Add new Markdown as a separate block without content_format; do not interpret stored Tiptap JSON as Markdown. Query blocks remain separate from text blocks.

Choose when results refresh. The default manual policy shows cached results in the app until you refresh. Set refresh_mode to on_load to refresh each distinct saved query when the workspace is opened in the app. Refreshes use normal query billing. Creating, editing, listing, or reading a workspace through MCP does not execute SQL or refresh its cache. Running SQL with run_query is separate and does not populate the workspace cache. For notebooks, set refresh_mode to interval with refresh_interval_seconds from 60 to 2592000 to schedule recurring refreshes. Scheduled queries use the owner’s team credits even while the notebook is closed. Overlapping refreshes are skipped.

Workspaces support up to 100 blocks, names up to 200 characters, descriptions up to 5,000 characters, and text content up to 50,000 characters per block. Each workspace tool’s arguments object is limited to 1 MiB. Notebook blocks cannot include layout. Legacy block widths are half or full; pixel height may be omitted, 0 for the default, or 200–1,200 pixels. Query and chart references must belong to your account.

Credits and limits

1,000 credits equal one dollar. Only successful queries are charged: one base credit, plus a scan charge at 3 credits per 400 MB, rounded down to whole credits, plus one credit per completed 5-second interval after the first 15 seconds. The examples below include the base and duration charges; scanned data is charged separately.

query durationbase + duration cost
1 second1 credit · $0.001
30 seconds4 credits · $0.004
60 seconds10 credits · $0.010
5 minutes58 credits · $0.058
60 minutes718 credits · $0.718
10,000 rowsper result set
60 minutesper query
5 req/sper API key
10 concurrentacross the entire service

Query requests share 10 concurrent slots across all API keys, dashboard users, and servers. This includes JSON execution, MCP, streaming, export creation, and saved-query refreshes. A slot remains occupied while a response is being delivered or retained background work is running. When capacity is full, the service returns 503 with Retry-After: 1. Wait at least one second, then retry with backoff.

Set spend limits and auto reload in Billing.

Errors

Errors return a JSON body with an error message and an optional code. Inspect both the HTTP status and the body when deciding how to handle a failure; not every error has a code. For example, a team spend-limit error includes a code:

429 Too Many Requests
{
  "error": "team spend limit exceeded",
  "code": "team_spend_limit_exceeded"
}
400only SELECT/WITH/EXPLAIN/SHOW statements are permitted

The body is malformed, the query is empty, the SQL fails to parse, or the statement is not read-only.

401missing or invalid API key

No Authorization header, or the key is wrong or revoked.

402insufficient credit balance

The team balance cannot cover the query, or the query ran past its byte budget.

413result set exceeds the maximum of 10000 rows / query exceeded the server's memory limit

The JSON result exceeds 10,000 rows or 8 MiB, an individual row exceeds 1 MiB, or the query exceeds server memory. For total output limits, return fewer rows, stream NDJSON, or create an export. The per-row and query-memory limits still apply to streaming and exports; narrow filters, reduce joins, or split the query to address memory limits.

429rate limit exceeded / team spend limit exceeded / API key spend limit exceeded

The key exceeded 5 requests in a sliding one-second window, the query would exceed the team's spend limit, or the API key reached its own spend limit. Inspect the error message and optional code: API key spend-limit errors have no code. Rate-limit responses include Retry-After: 1. Spend-limit errors require adjusting the applicable limit or waiting for its reset.

503billing unavailable / query capacity exhausted

Billing is unavailable, the shared capacity of 10 concurrent query requests is full, or the capacity check is unavailable. Capacity-exhausted responses include Retry-After: 1. Retry with backoff; check any returned export ID before creating another export.

504query exceeded the time limit

The query hit the 60 minute limit or a shorter limit based on available credits.

Run your first query.

Open the app

Questions or missing data? Write to support@outcome.sh. Signing up with a .edu email grants $20 in free query credits. Read the .edu credits guide.