> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a structured query across one or more tables

> Runs a structured query against Clay table data and returns records with field metadata.



## OpenAPI

````yaml /openapi.json post /tables/query
openapi: 3.1.0
info:
  contact:
    name: Clay
    url: https://www.clay.com
  description: Programmatic access to Clay.
  title: Clay Public API
  version: '0'
servers:
  - description: production
    url: https://api.clay.com/public/v0
security:
  - ClayApiKey: []
tags:
  - description: Authenticated user and workspace endpoints.
    name: me
  - description: Search creation and pagination endpoints.
    name: searches
  - description: Structured table query endpoints.
    name: tables
  - description: Routine discovery and execution endpoints.
    name: routines
paths:
  /tables/query:
    post:
      tags:
        - tables
      summary: Run a structured query across one or more tables
      description: >-
        Runs a structured query against Clay table data and returns records with
        field metadata.
      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'
components:
  schemas:
    StructuredQueryRequest:
      additionalProperties: false
      properties:
        cursor:
          type: string
        limit:
          default: 50
          maximum: 100
          minimum: 1
          type: integer
        query:
          $ref: '#/components/schemas/StructuredQuery'
      required:
        - query
      type: object
    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
    ErrorResponse:
      additionalProperties: false
      properties:
        message:
          type: string
      required:
        - message
      type: object
    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:
          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
    CellResult:
      anyOf:
        - $ref: '#/components/schemas/CellSuccess'
        - $ref: '#/components/schemas/CellError'
        - $ref: '#/components/schemas/CellPending'
        - $ref: '#/components/schemas/CellEmpty'
    FieldMeta:
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
      required:
        - id
        - name
        - type
      type: object
    FilterExpression:
      anyOf:
        - $ref: '#/components/schemas/FilterPredicate'
        - $ref: '#/components/schemas/FilterAnd'
        - $ref: '#/components/schemas/FilterOr'
        - $ref: '#/components/schemas/FilterNot'
    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
    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
    CellError:
      additionalProperties: false
      properties:
        error:
          type: string
        status:
          const: error
          type: string
      required:
        - status
      type: object
    CellPending:
      additionalProperties: false
      properties:
        status:
          enum:
            - running
            - queued
            - retry
            - rate_limited
            - awaiting_callback
          type: string
      required:
        - status
      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:
                type:
                  - string
                  - number
              type: array
      required:
        - field
        - op
      type: object
    FilterAnd:
      additionalProperties: false
      properties:
        and:
          items:
            $ref: '#/components/schemas/FilterExpression'
          maxItems: 10
          minItems: 1
          type: array
      required:
        - and
      type: object
    FilterOr:
      additionalProperties: false
      properties:
        or:
          items:
            $ref: '#/components/schemas/FilterExpression'
          maxItems: 10
          minItems: 1
          type: array
      required:
        - or
      type: object
    FilterNot:
      additionalProperties: false
      properties:
        not:
          $ref: '#/components/schemas/FilterExpression'
      required:
        - not
      type: object
    NestedPath:
      items:
        minLength: 1
        type: string
      maxItems: 5
      minItems: 1
      type: array
  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

````