Skip to content

Documentation

Query 13F holdings, insider and congressional trades, financials and macro data over REST or MCP. Start with a request, connect an AI agent, or open the API reference.

REST base URL: https://api.ko.io

Make a first call

Request Berkshire Hathaway’s latest 13F holdings in demo mode: no key, no sign-up. The filing that row came from is shown below it.
curl "https://api.ko.io/api/v1/holdings/1067983?per_page=1&demo=true"
Response

Abridged response captured Sep 25, 2026 (quarter ending Jun 30, 2026). Run it for the live response; no key or sign-up needed. A newer quarter may be returned.

{
  "data": [
    {
      "cik": "1067983",
      "quarter_date": "2026-06-30",
      "ticker": "AAPL",
      "name_of_issuer": "APPLE INC",
      "shares_held": "227917808",
      "holding_value": "65950296923",
      "total_portfolio_value": "299253556246",
      "portfolio_weight_pct": 22.04,
      "action": "UNCHANGED",
      "share_change": "0",
      "prev_shares": "227917808",
      "prev_value": "57843260493",
      "is_option": 0,
      "call_shares": "0",
      "put_shares": "0"
    }
  ]
}
Filer
Berkshire Hathaway
Ticker
AAPL
Shares
227,917,808
Filing lines combined
12
SourceSEC EDGAR13F-HR0001193125-26-352200 ↗period 2026-06-30filed 2026-08-14

The row does not carry its accession number. The 13F-HR it was parsed from (quarter ending Jun 30, 2026, captured Sep 25, 2026) is listed by GET /api/v1/filings/1067983?form=13F-HR. A newer quarter returns a newer filing.

Next, create a Free account and a key in Console → API keys, then send it in the Authorization header as a Bearer token (below). Paginate with page and per_page. The Quickstart has the same call in curl, Python and MCP; the Playground runs requests with your key.

Authentication

Send your API key as a Bearer token in the Authorization header. Keys start with ko_live_; create them in the Console.
curl "https://api.ko.io/api/v1/holdings/1067983" \
  -H "Authorization: Bearer ko_live_your_key_here"

Demo mode

Add ?demo=true to a Free-plan endpoint to call it without a key. Demo mode allows about 1,000 requests an hour per IP and sends no rate-limit headers. Pro and Builder endpoints return 403 PLAN_REQUIRED.
Web-app sign-in endpoints (session auth for the website, not for API keys)
  • POST/api/auth/google
  • POST/api/auth/login
  • POST/api/auth/register
  • POST/api/auth/logout
  • POST/api/auth/forgot-password
  • POST/api/auth/reset-password
  • GET/api/auth/me
  • PUT/api/auth/profile

Response and provenance

Data endpoints return { data, meta } on success and { error: { code, message } } on failure. data is an array for lists and an object for single resources; file and document endpoints are described in the reference.
List response200 OK
{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total_count": "1234",
    "query_time_ms": 3.1
  }
}
Object response200 OK
{
  "data": { ... },
  "meta": {
    "query_time_ms": 2.1
  }
}

Provenance

SEC data is normalized from public filings. 13F, Form 4 and similar REST rows do not include an accession number. Use the filing lookup endpoints to locate source documents. List a filer’s filings with /api/v1/filings/:cik, then open one with /api/v1/filings/:cik/:accession. Numeric fields often arrive as strings (for example "holding_value": "65950296923"); parse them before arithmetic.

Connect an AI agent

24 tools
The MCP server at https://mcp.ko.io/mcp gives Claude Code, Codex, Cursor, Grok (xAI API), Gemini CLI and other MCP clients the same data as the REST API. MCP tool calls and REST requests share one daily quota.
Claude Code
claude mcp add ko-sec-data --transport http https://mcp.ko.io/mcp

Configs for every client, demo mode and API-key options, and the searchable list of all 24 tools with their plans are on the MCP page. For a worked example, follow Build an SEC agent.

Endpoint groups

Open API reference

The core data endpoints by group, one line each. Each line opens its entry in the API reference, which has the parameters, response formats and runnable requests, plus the crypto ETF, N-PORT, Reg SHO and filings gateway endpoints not listed here. Endpoints without a plan label work on the Free plan and in demo mode.

44 core endpoints in 17 groups

Institutions

4

Holdings

1

Stocks and companies

7

Stock ownership

2

Insider trades

2

Congress trades

4

Other SEC filings

6

Treasury

3

Federal Reserve

3

Economic indicators

1

Market structure

2

Energy

1

Banking

3

Financial stress

1

Bulk export

1

Dashboard

2

Plans and rate limits

Limits apply per account on a daily window that resets at 00:00 UTC.
Plan
Calls / day
Rows / request
Price
Free
200
500
$0
Pro
20,000
5,000
$60/mo
Builder
200,000
50,000
$250/mo

Monthly prices; annual billing is cheaper and shown on Pricing, along with what each plan includes. Free covers the most recent quarter and latest data only; full history needs Pro or higher. MCP tool calls and REST requests share one quota. Requests made with an API key return X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, plus Retry-After on a 429. Demo mode (no key) allows about 1,000 requests an hour per IP and sends none of these headers.

Errors

400
Bad request
Check the query parameters and the path format.
401
Missing or invalid key
Send a valid API key, or use ?demo=true on a Free-plan endpoint.
403
Plan required
Your plan does not include this endpoint or feature.
404
Not found
Check the path and the identifier (CIK, ticker, slug).
429
Rate limited
With a key, read Retry-After and the X-RateLimit headers; a daily quota resets at 00:00 UTC. In demo mode, wait up to an hour or use a Free API key.
500
Server error
Retry after a few seconds.
Error response401
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing or invalid API key. Get one at https://ko.io/console/keys"
  }
}
Error response403
{
  "error": {
    "code": "PLAN_REQUIRED",
    "message": "This endpoint requires a paid plan. Upgrade at https://ko.io/pricing"
  }
}