# Outcome data API and MCP reference Canonical documentation: https://docs.outcome.sh/ OpenAPI data-access subset: https://docs.outcome.sh/openapi.json Agent guide: https://outcome.sh/guides/prediction-market-data-for-ai-agents API base: https://api.outcome.sh ## What Outcome provides SQL access to Kalshi and Polymarket market metadata, current market state, historical trade observations, and resolved outcomes. Use it for research, historical price/volume analysis, comparing contracts across venues, and calibration studies. Outcome's documented data API is read-only; it does not place trades. GET /v1/schema is the authoritative current schema. Available tables include: - market_metadata: market identifiers, titles, rules, lifecycle and settlement metadata. - markets: market metadata together with current prices, volume, and other available market-state fields. - trades: timestamped trade observations, prices, contract counts, and side/identity fields. - resolved_markets: venue, ticker, and recorded result labels. Columns can be nullable or venue-specific. Do not assume order-book depth, every trade, a universal history start date, or a latency guarantee. Inspect coverage and timestamps for the requested venue, ticker, and time range. Similar titles do not establish equivalent resolution rules. ## Start without credentials GET https://api.outcome.sh/v1/schema No authentication or billing. Response: {"tables":[{"name":"markets","columns":[{"name":"venue","type":"LowCardinality(String)"},{"name":"ticker","type":"String"}]}]} This is an abbreviated shape example, not the complete schema. Fetch the endpoint to obtain all current columns. ## Authentication and query execution Create an account at https://app.outcome.sh/login, then create an API key at https://app.outcome.sh/keys. Queries use the team's credits. Send the key only in the Authorization header, not in URLs or public notebooks. POST https://api.outcome.sh/v1/execute Authorization: Bearer $OUTCOME_API_KEY Content-Type: application/json {"query":"SELECT venue, ticker, title, yes_price, updated_time FROM markets WHERE is_deleted = 0 ORDER BY volume_24h DESC LIMIT 5"} The response is a JSON array of row objects, not a {data: ...} envelope. Field names and values depend on the selected columns. Empty results are []. Usage headers include X-Credits-Used (computed cost), X-Duration-Ms, and X-Bytes-Read. X-Credits-Remaining is present when charging succeeds; computed cost alone is not proof of a debit. The required query is one read-only ClickHouse SQL statement: SELECT, WITH, EXPLAIN, or SHOW. Writes, system access, external-data functions, and user SETTINGS, FORMAT, or INTO clauses are rejected. Optional final: true applies deduplication to markets/trades and may increase scanned data. Preserve venue plus ticker as the identifier, filter is_deleted = 0 where that column exists, and inspect result labels before assuming binary settlement. ## Costs, limits, and errors Schema discovery is free. Data queries use credits; 1,000 credits equal USD 1. Successful billable queries have a base charge plus charges for scanned bytes and runtime. See https://docs.outcome.sh/#credits for the current formula. LIMIT bounds returned rows, not bytes scanned; constrain markets, columns, and time windows as well. JSON queries are limited to 10,000 rows, 8 MiB total output, 1 MiB per row, and 60 minutes of execution. Credit balance may impose a shorter limit. Each API key allows 5 requests per second across rate-limited endpoints. Streaming and exports are documented at https://docs.outcome.sh/#exports; for streaming, require the final successful completion record instead of treating HTTP 200 alone as success. Errors use a JSON object with error and sometimes code. Handle 400 by correcting the request/SQL; 401 by checking the key; 402 by checking credits; 413 by reducing output or query memory use (streaming/exports help output limits, not memory limits). Distinguish 429 rate limits from API-key and team spend limits using error and optional code; honor Retry-After when present. Back off on 503 capacity errors. Narrow or simplify queries that return 504 execution timeouts. Do not repeatedly retry a query that can spend credits without understanding its outcome. ## MCP connection Remote endpoint: https://api.outcome.sh/v1/mcp Authentication: Authorization: Bearer $OUTCOME_API_KEY Transport: HTTP POST with JSON-RPC 2.0. No SDK required. Discover the current tool contracts: POST https://api.outcome.sh/v1/mcp Content-Type: application/json Authorization: Bearer $OUTCOME_API_KEY {"jsonrpc":"2.0","id":1,"method":"tools/list"} Data tools: - list_tables: free table and column discovery. - describe_table: free schema for one table. - preview_table: billed bounded sample; default 10 rows, maximum 100. - run_query: billed read-only SQL, using the same execution limits as /v1/execute. Example tool call: {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"run_query","arguments":{"query":"SELECT venue, ticker, title FROM market_metadata WHERE is_deleted = 0 LIMIT 5"}}} Read the MCP content payload and isError flag. run_query includes JSON text with rows, row_count, bytes_read, credits_used, charged, and duration_ms. The server also exposes saved-query and notebook management tools; obtain their current arguments from tools/list. Saving a query or notebook does not execute SQL or refresh its cached results. Full setup and editing semantics: https://docs.outcome.sh/#mcp. ## Verify and cite a result Check the live schema before composing SQL. Discover actual venue/ticker pairs, inspect rules and available timestamps, then bound the query to the relevant markets and window. Record the query, retrieval time, venue, ticker, observation timestamps, and known gaps. Current state is not historical state, and the newest observed trade does not prove complete collection. Cite Outcome as the data access source and name the underlying venue. For public research, cite the canonical notebook URL and author; distinguish the author's analysis from the underlying data. https://outcome.sh/explore/feed.json provides public document links and author metadata. Append /text to a canonical public notebook URL to read prose and bounded cached results. Cache timestamps and notebook edit dates are not market observation times. Never expose API keys in a citation.