Skip to main content
POST
/
v2
/
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
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).

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
  },
  {
    "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.

Example:
{
  "columns": [
    { "name": "block_number", "type": "UInt64" },
    {
      "name": "transaction_hash",
      "type": "String"
    }
  ]
}
​
metadata
object

Metadata about query execution.

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