Run SQL Query

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/data/query/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "sql": "SELECT block_number, transaction_hash FROM base.transactions WHERE block_number > 1000000 LIMIT 10",
  "cache": {
    "maxAgeMs": 1000
  }
}'

{
  "result": [
    {
      "event_signature": "Transfer(address,address,uint256)",
      "from": "0x1234567890abcdef",
      "to": "0x1234567890abcdef",
      "amount": 1000000000000000000
    },
    {
      "event_signature": "Transfer(address,address,uint256)",
      "from": "0x1234567890abcdef",
      "to": "0x1234567890abcdef",
      "amount": 2000000000000000000
    }
  ],
  "schema": {
    "columns": [
      {
        "name": "block_number",
        "type": "UInt64"
      },
      {
        "name": "transaction_hash",
        "type": "String"
      }
    ]
  },
  "metadata": {
    "cached": false,
    "executionTimestamp": "2025-01-01T00:00:00.000Z",
    "executionTimeMs": 145,
    "rowCount": 2
  }
}

Run SQL Query

Run a read-only SQL query against indexed blockchain data including transactions, events, and decoded logs.

This endpoint provides direct SQL access to comprehensive blockchain data across supported networks. Queries are executed against optimized data structures for high-performance analytics.

Allowed Queries

Standard SQL syntax (ClickHouse dialect)
Read-only queries (SELECT statements)
No DDL or DML operations
No cartesian products

Supported Tables

base.events - Base mainnet decoded event logs with parameters, event signature, topics, and more.
base.transactions - Base mainnet transaction data including hash, block number, gas usage.
base.blocks - Base mainnet block information.
base.encoded_logs - Encoded log data of event logs that aren’t able to be decoded by our event decoder (ex: log0 opcode).
base.transfers - All event logs with event signature Transfer(address,address,uint256). ERC-20, ERC-721, and ERC-1155 transfers are all included.

Query Limits

Maximum result set: 100,000 rows
Query timeout: 30 seconds

POST

data

query

run

Run SQL Query

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/data/query/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "sql": "SELECT block_number, transaction_hash FROM base.transactions WHERE block_number > 1000000 LIMIT 10",
  "cache": {
    "maxAgeMs": 1000
  }
}'

{
  "result": [
    {
      "event_signature": "Transfer(address,address,uint256)",
      "from": "0x1234567890abcdef",
      "to": "0x1234567890abcdef",
      "amount": 1000000000000000000
    },
    {
      "event_signature": "Transfer(address,address,uint256)",
      "from": "0x1234567890abcdef",
      "to": "0x1234567890abcdef",
      "amount": 2000000000000000000
    }
  ],
  "schema": {
    "columns": [
      {
        "name": "block_number",
        "type": "UInt64"
      },
      {
        "name": "transaction_hash",
        "type": "String"
      }
    ]
  },
  "metadata": {
    "cached": false,
    "executionTimestamp": "2025-01-01T00:00:00.000Z",
    "executionTimeMs": 145,
    "rowCount": 2
  }
}

Authorizations

Authorization

string

header

required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Body

application/json

Request to execute a SQL query against indexed blockchain data.

sql

string

required

SQL query to execute against the indexed blockchain data.

Required string length: 1 - 100000

Example:

"SELECT block_number, transaction_hash FROM base.transactions WHERE block_number > 1000000 LIMIT 10"

cache

Query result cache configuration · object

Enables control over how often queries need to be fully re-executed on the backing store. This can be useful in scenarios where API calls might be made frequently, API latency is critical, and some freshness lag (ex: 750ms, 2s, 5s) is tolerable. By default, each query result is returned from cache so long as the result is from an identical query and less than 500ms old. This freshness tolerance can be modified upwards, to a maximum of 300000ms (i.e. 300s, 5m).

Show child attributes

cache.maxAgeMs

integer

default:500

The maximum tolerable staleness of the query result cache in milliseconds. If a previous execution result of an identical query is older than this age, the query will be re-executed. If the data is less than this age, the result will be returned from cache.

Required range: 500 <= x <= 300000

Example:

1000

Example:

{ "maxAgeMs": 1000 }

Response

Query run successfully.

Result of executing a SQL query.

result

object[]

Query result as an array of objects representing rows.

Row data with column names as keys.

Example:

{
  "event_signature": "Transfer(address,address,uint256)",
  "from": "0x1234567890abcdef",
  "to": "0x1234567890abcdef",
  "amount": 1000000000000000000
}

Example:

[
  {
    "event_signature": "Transfer(address,address,uint256)",
    "from": "0x1234567890abcdef",
    "to": "0x1234567890abcdef",
    "amount": 1000000000000000000
  },
  {
    "event_signature": "Transfer(address,address,uint256)",
    "from": "0x1234567890abcdef",
    "to": "0x1234567890abcdef",
    "amount": 2000000000000000000
  }
]

schema

object

Schema information for the query result. This is a derived schema from the query result, so types may not match the underlying table.

Show child attributes

schema.columns

object[]

Column definitions.

Show child attributes

name

string

Column name.

type

enum<string>

Column data type (ClickHouse types).

Available options:

String,

UInt8,

UInt16,

UInt32,

UInt64,

UInt128,

UInt256,

Int8,

Int16,

Int32,

Int64,

Int128,

Int256,

Float32,

Float64,

Bool,

Date,

DateTime,

DateTime64,

UUID

Example:

{
  "name": "event_signature",
  "type": "String",
  "description": "The signature of the event."
}

Example:

{
  "columns": [
    { "name": "block_number", "type": "UInt64" },
    {
      "name": "transaction_hash",
      "type": "String"
    }
  ]
}

metadata

object

Metadata about query execution.

Show child attributes

metadata.cached

boolean

Whether the result was served from the query result cache.

Example:

false

metadata.executionTimestamp

string<date-time>

When the query result was executed against the backing store in RFC 3339 format.

Example:

"2025-01-01T00:00:00.000Z"

metadata.executionTimeMs

integer

Query execution time in milliseconds.

Example:

145

metadata.rowCount

integer

Number of rows returned.

Example:

2

Example:

{
  "cached": false,
  "executionTimestamp": "2025-01-01T00:00:00.000Z",
  "executionTimeMs": 145,
  "rowCount": 2
}

⌘I

CDP API V2

REST API

Run SQL Query

Allowed Queries

Supported Tables

Query Limits

Authorizations

Body

Response