Clay

Clay Tables API

Structured table query endpoints.

GitHub OpenAPI

Operations 1

POST /tables/query Run a structured query across one or more tables #

Documentation

📖
APIReference
https://developers.clay.com/api-reference/me/get-the-authenticated-user
📖
Documentation
https://developers.clay.com
📖
Authentication
https://developers.clay.com/public-api/authentication
📖
RateLimits
https://raw.githubusercontent.com/api-evangelist/clay-com/refs/heads/main/rate-limits/clay-com-rate-limits.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/clay-com/refs/heads/main/openapi/clay-com-tables-api-openapi.yml

Other Resources

🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/clay-com/refs/heads/main/data-model/clay-com-data-model.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/clay-com/refs/heads/main/errors/clay-com-problem-types.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/clay-com-tables-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

clay-com-tables-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  contact:
    name: Clay
    url: https://www.clay.com
  description: Programmatic access to Clay.
  title: Clay Public Tables API
  version: '0'
servers:
- description: production
  url: https://api.clay.com/public/v0
security:
- ClayApiKey: []
tags:
- description: Structured table query endpoints.
  name: tables
paths:
  /tables/query:
    post:
      description: '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.'
      operationId: query
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StructuredQueryRequest'
        description: Body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
          description: '200'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '400'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '401'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '403'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '404'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '422'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: '429'
      summary: Run a structured query across one or more tables
      tags:
      - tables
components:
  schemas:
    QueryResponse:
      additionalProperties: false
      properties:
        cursor:
          type: string
        data:
          items:
            additionalProperties:
              $ref: '#/components/schemas/CellResult'
            type: object
          type: array
        fields:
          additionalProperties:
            $ref: '#/components/schemas/FieldMeta'
          type: object
      required:
      - data
      type: object
    FilterOr:
      additionalProperties: false
      properties:
        or:
          items:
            $ref: '#/components/schemas/FilterExpression'
          maxItems: 10
          minItems: 1
          type: array
      required:
      - or
      type: object
    FilterAnd:
      additionalProperties: false
      properties:
        and:
          items:
            $ref: '#/components/schemas/FilterExpression'
          maxItems: 10
          minItems: 1
          type: array
      required:
      - and
      type: object
    CellEmpty:
      additionalProperties: false
      properties:
        status:
          const: empty
          type: string
      required:
      - status
      type: object
    FilterPredicate:
      additionalProperties: false
      properties:
        field:
          minLength: 1
          type: string
        op:
          enum:
          - '='
          - '!='
          - '>'
          - '>='
          - <
          - <=
          - contains
          - not_contains
          - starts_with
          - ends_with
          - in
          - not_in
          - is_empty
          - is_not_empty
          type: string
        path:
          $ref: '#/components/schemas/NestedPath'
        value:
          anyOf:
          - type: string
          - type: number
          - type: boolean
          - items:
              anyOf:
              - type: string
              - type: number
            type: array
      required:
      - field
      - op
      type: object
    FieldMeta:
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
      required:
      - id
      - name
      - type
      type: object
    CellResult:
      oneOf:
      - $ref: '#/components/schemas/CellSuccess'
      - $ref: '#/components/schemas/CellError'
      - $ref: '#/components/schemas/CellPending'
      - $ref: '#/components/schemas/CellEmpty'
    CellSuccess:
      additionalProperties: false
      properties:
        fields:
          anyOf:
          - additionalProperties: {}
            type: object
          - type: 'null'
        is_stale:
          const: true
          type: boolean
        status:
          const: success
          type: string
        value: {}
      required:
      - status
      - fields
      type: object
    FilterNot:
      additionalProperties: false
      properties:
        not:
          $ref: '#/components/schemas/FilterExpression'
      required:
      - not
      type: object
    AggregateSelect:
      additionalProperties: false
      properties:
        as:
          minLength: 1
          type: string
        field:
          minLength: 1
          type: string
        fn:
          enum:
          - count
          - sum
          - avg
          - max
          - min
          type: string
        path:
          $ref: '#/components/schemas/NestedPath'
      required:
      - fn
      - field
      - as
      type: object
    FieldSelect:
      additionalProperties: false
      properties:
        as:
          type: string
        field:
          minLength: 1
          type: string
        path:
          $ref: '#/components/schemas/NestedPath'
        table:
          type: string
      required:
      - field
      type: object
    StructuredQueryRequest:
      additionalProperties: false
      properties:
        cursor:
          description: '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.'
          type: string
        limit:
          default: 50
          maximum: 100
          minimum: 1
          type: integer
        query:
          $ref: '#/components/schemas/StructuredQuery'
      required:
      - query
      type: object
    ErrorResponse:
      additionalProperties: false
      properties:
        message:
          type: string
      required:
      - message
      type: object
    NestedPath:
      items:
        minLength: 1
        type: string
      maxItems: 5
      minItems: 1
      type: array
    StructuredQuery:
      additionalProperties: false
      properties:
        field_mode:
          enum:
          - names
          - ids
          type: string
        filter:
          $ref: '#/components/schemas/FilterExpression'
        group_by:
          items:
            minLength: 1
            type: string
          maxItems: 5
          type: array
        join:
          items:
            additionalProperties: false
            properties:
              'on':
                additionalProperties: false
                properties:
                  left:
                    minLength: 1
                    type: string
                  right:
                    minLength: 1
                    type: string
                required:
                - left
                - right
                type: object
              table:
                minLength: 1
                type: string
              type:
                default: inner
                enum:
                - inner
                - left
                type: string
            required:
            - table
            - 'on'
            type: object
          maxItems: 4
          type: array
        order_by:
          description: Custom sort. Queries with a custom order_by do not support cursor pagination.
          items:
            additionalProperties: false
            properties:
              direction:
                default: asc
                enum:
                - asc
                - desc
                type: string
              field:
                minLength: 1
                type: string
            required:
            - field
            type: object
          maxItems: 3
          type: array
        select:
          items:
            anyOf:
            - $ref: '#/components/schemas/AggregateSelect'
            - $ref: '#/components/schemas/FieldSelect'
          maxItems: 20
          type: array
        tables:
          items:
            additionalProperties: false
            properties:
              alias:
                type: string
              id:
                minLength: 1
                type: string
            required:
            - id
            type: object
          maxItems: 5
          minItems: 1
          type: array
      required:
      - tables
      type: object
    CellError:
      additionalProperties: false
      properties:
        error:
          type: string
        status:
          const: error
          type: string
      required:
      - status
      type: object
    FilterExpression:
      anyOf:
      - $ref: '#/components/schemas/FilterPredicate'
      - $ref: '#/components/schemas/FilterAnd'
      - $ref: '#/components/schemas/FilterOr'
      - $ref: '#/components/schemas/FilterNot'
    CellPending:
      additionalProperties: false
      properties:
        status:
          enum:
          - running
          - queued
          - retry
          - rate_limited
          - awaiting_callback
          type: string
      required:
      - status
      type: object
  securitySchemes:
    ClayApiKey:
      description: Personal API key tied to your Clay user. Create one under Settings → Account in the Clay app.
      in: header
      name: clay-api-key
      type: apiKey