Run a structured query across one or more tables

Runs a structured query against Clay table data and returns records with field metadata. Results are paginated: pass the returned cursor back to fetch the next page. Scans return rows in least-recently-updated-first order and reflect writes that land while you paginate — a scan returns every record visible when it started and picks up records written while it runs, and a record updated mid-scan can be returned again with fresher data, so deduplicate by id if you need each record once.

POST

https://api.clay.com/public/v0

tables

query

Run a structured query across one or more tables

curl --request POST \
  --url https://api.clay.com/public/v0/tables/query \
  --header 'Content-Type: application/json' \
  --header 'clay-api-key: <api-key>' \
  --data '
{
  "query": {
    "tables": [
      {
        "id": "<string>",
        "alias": "<string>"
      }
    ],
    "filter": {
      "field": "<string>",
      "path": [
        "<string>"
      ],
      "value": "<string>"
    },
    "group_by": [
      "<string>"
    ],
    "join": [
      {
        "on": {
          "left": "<string>",
          "right": "<string>"
        },
        "table": "<string>",
        "type": "inner"
      }
    ],
    "order_by": [
      {
        "field": "<string>",
        "direction": "asc"
      }
    ],
    "select": [
      {
        "as": "<string>",
        "field": "<string>",
        "path": [
          "<string>"
        ]
      }
    ]
  }
}
'

const options = {
  method: 'POST',
  headers: {'clay-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: {
      tables: [{id: '<string>', alias: '<string>'}],
      filter: {field: '<string>', path: ['<string>'], value: '<string>'},
      group_by: ['<string>'],
      join: [{on: {left: '<string>', right: '<string>'}, table: '<string>', type: 'inner'}],
      order_by: [{field: '<string>', direction: 'asc'}],
      select: [{as: '<string>', field: '<string>', path: ['<string>']}]
    }
  })
};

fetch('https://api.clay.com/public/v0/tables/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.clay.com/public/v0/tables/query"

payload = { "query": {
        "tables": [
            {
                "id": "<string>",
                "alias": "<string>"
            }
        ],
        "filter": {
            "field": "<string>",
            "path": ["<string>"],
            "value": "<string>"
        },
        "group_by": ["<string>"],
        "join": [
            {
                "on": {
                    "left": "<string>",
                    "right": "<string>"
                },
                "table": "<string>",
                "type": "inner"
            }
        ],
        "order_by": [
            {
                "field": "<string>",
                "direction": "asc"
            }
        ],
        "select": [
            {
                "as": "<string>",
                "field": "<string>",
                "path": ["<string>"]
            }
        ]
    } }
headers = {
    "clay-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": [
    {}
  ],
  "cursor": "<string>",
  "fields": {}
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

Authorizations

clay-api-key

string

header

required

Personal API key tied to your Clay user. Create one under Settings → Account in the Clay app.

Body

application/json

Body

query

object

required

Show child attributes

cursor

string

Opaque cursor from the previous response. Scans page in least-recently-updated-first order and reflect concurrent writes: a record updated mid-scan can be returned again, so deduplicate by id.

limit

integer

default:50

Required range: 1 <= x <= 100

Response

200

data

object[]

required

Show child attributes

cursor

string

fields

object

Show child attributes

Run a structured query across one or more tables

curl --request POST \
  --url https://api.clay.com/public/v0/tables/query \
  --header 'Content-Type: application/json' \
  --header 'clay-api-key: <api-key>' \
  --data '
{
  "query": {
    "tables": [
      {
        "id": "<string>",
        "alias": "<string>"
      }
    ],
    "filter": {
      "field": "<string>",
      "path": [
        "<string>"
      ],
      "value": "<string>"
    },
    "group_by": [
      "<string>"
    ],
    "join": [
      {
        "on": {
          "left": "<string>",
          "right": "<string>"
        },
        "table": "<string>",
        "type": "inner"
      }
    ],
    "order_by": [
      {
        "field": "<string>",
        "direction": "asc"
      }
    ],
    "select": [
      {
        "as": "<string>",
        "field": "<string>",
        "path": [
          "<string>"
        ]
      }
    ]
  }
}
'

const options = {
  method: 'POST',
  headers: {'clay-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: {
      tables: [{id: '<string>', alias: '<string>'}],
      filter: {field: '<string>', path: ['<string>'], value: '<string>'},
      group_by: ['<string>'],
      join: [{on: {left: '<string>', right: '<string>'}, table: '<string>', type: 'inner'}],
      order_by: [{field: '<string>', direction: 'asc'}],
      select: [{as: '<string>', field: '<string>', path: ['<string>']}]
    }
  })
};

fetch('https://api.clay.com/public/v0/tables/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.clay.com/public/v0/tables/query"

payload = { "query": {
        "tables": [
            {
                "id": "<string>",
                "alias": "<string>"
            }
        ],
        "filter": {
            "field": "<string>",
            "path": ["<string>"],
            "value": "<string>"
        },
        "group_by": ["<string>"],
        "join": [
            {
                "on": {
                    "left": "<string>",
                    "right": "<string>"
                },
                "table": "<string>",
                "type": "inner"
            }
        ],
        "order_by": [
            {
                "field": "<string>",
                "direction": "asc"
            }
        ],
        "select": [
            {
                "as": "<string>",
                "field": "<string>",
                "path": ["<string>"]
            }
        ]
    } }
headers = {
    "clay-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": [
    {}
  ],
  "cursor": "<string>",
  "fields": {}
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

Start here

Core primitives

Recipes

Concepts

API Reference

Run a structured query across one or more tables

Authorizations

Body

Response