Documentation

Quickstart

From API key to first query in 2 minutes.

1. Create an account or sign in
2. Copy your API key from Settings
3. Search for a dataset:

curl -s "https://api.subsets.io/api/public/search?q=inflation&type=dataset"

4. Query it with SQL:

curl -s -X POST "https://api.subsets.io/api/datasets/bis-ws-long-cpi/query" \
  -H "Authorization: Bearer sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT time_period, obs_value FROM \"bis-ws-long-cpi\" WHERE series_key = '\''A.CZ.771'\'' ORDER BY time_period DESC LIMIT 10"}'

Returns { columns, rows, row_count }. Uses 1 of your monthly queries.

Authentication

Search, list, and preview are public — no auth needed. SQL queries require authentication.

Authorization: Bearer sk_YOUR_KEY

{
  "env": { "SUBSETS_API_KEY": "sk_YOUR_KEY" }
}

export SUBSETS_API_KEY=sk_YOUR_KEY

API keys start with sk_ and are available on your Settings page.

Queries & Rate Limits

Free tier: 500 queries/month. Pro: 5,000 queries/month. Your quota resets on the 1st of each month.

Rate limits: Public endpoints are limited to 60 requests per minute per IP. The X-Credits-Remaining header on API responses reports how many queries you have left this month.

Search

Search across datasets by keyword.

curl -s "https://api.subsets.io/api/public/search?q=carbon&type=dataset&limit=20"

Parameters: q (query), type (dataset), limit (1-50). No auth required.

Datasets

Get metadata, schema, and preview rows for any published dataset.

Get dataset details

curl -s "https://api.subsets.io/api/public/datasets/bis-ws-long-cpi"

Returns schema (column names and types), row count, description, tags, and license.

Preview rows

curl -s "https://api.subsets.io/api/public/datasets/bis-ws-long-cpi/preview?limit=10"

Returns { columns, rows, row_count }. Max 100 rows.

SQL Queries

Execute SQL queries against datasets. Use dataset IDs as table names in your SQL. Results are returned directly — nothing is saved.

Wrap hyphenated dataset IDs in double quotes so the SQL parser doesn't read them as subtraction.

Query a single dataset

curl -s -X POST "https://api.subsets.io/api/datasets/bis-ws-long-cpi/query" \
  -H "Authorization: Bearer sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT time_period, obs_value FROM \"bis-ws-long-cpi\" ORDER BY time_period DESC LIMIT 10"}'

Returns { columns, rows, row_count }. Each execution uses 1 of your monthly queries.

Client Setup

All capabilities above are shown as REST API examples. Here's how to set up the MCP server or Claude Code skill for tool-based access.

claude mcp add --transport http subsets https://mcp.subsets.io --header "Authorization: Bearer sk_YOUR_KEY"

{
  "mcpServers": {
    "subsets": {
      "url": "https://mcp.subsets.io",
      "headers": {
        "Authorization": "Bearer sk_YOUR_KEY"
      }
    }
  }
}

Error Reference