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

# Clay Enterprise: Clay Query

> Run a structured query across one or more tables. Includes SDK V2 guidance, input constraints, response fields, and Deepline credit cost.

Run a structured query across one or more tables.

<Info>
  Tool ID: `clay_query`
</Info>

## Run this action

Use the TypeScript SDK for a single call. Put `ctx.tools.execute(...)` inside a Play when the call should be durable, scheduled, or run across a CSV.

```ts theme={null}
import { Deepline } from 'deepline';

const deepline = await Deepline.connect();
const result = await deepline.tools.execute(
  'clay_query',
  {
    "query": {
      "tables": [
        {
          "id": "id_123"
        }
      ]
    }
  },
);

console.log(result.toolResponse.raw);
```

### CLI

```bash theme={null}
deepline tools execute clay_query --input '{
  "query": {
    "tables": [
      {
        "id": "id_123"
      }
    ]
  }
}' --json
```

## Example response

The static output schema is not detailed enough to generate a reliable example. Use `deepline tools get clay_query --json` for the complete live contract.

## Input reference

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.

| Name             | Type      | Required | Default | Details                                                                                                                                                                                          |
| ---------------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `payload.cursor` | `string`  | No       | —       | 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. |
| `payload.limit`  | `integer` | No       | `50`    | Minimum: 1. Maximum: 100.                                                                                                                                                                        |
| `payload.query`  | `object`  | Yes      | —       | —                                                                                                                                                                                                |

<details>
  <summary>Show raw input schema</summary>

  ### Input JSON Schema

  ```json theme={null}
  {
    "type": "object",
    "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.",
    "properties": {
      "cursor": {
        "type": "string",
        "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."
      },
      "limit": {
        "type": "integer",
        "default": 50,
        "minimum": 1,
        "maximum": 100
      },
      "query": {
        "type": "object",
        "properties": {
          "field_mode": {
            "type": "string",
            "enum": [
              "names",
              "ids"
            ]
          },
          "filter": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "field": {
                    "type": "string",
                    "minLength": 1
                  },
                  "op": {
                    "type": "string",
                    "enum": [
                      "=",
                      "!=",
                      ">",
                      ">=",
                      "<",
                      "<=",
                      "contains",
                      "not_contains",
                      "starts_with",
                      "ends_with",
                      "in",
                      "not_in",
                      "is_empty",
                      "is_not_empty"
                    ]
                  },
                  "path": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 5,
                    "items": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "value": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "array",
                        "items": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "number"
                            }
                          ]
                        }
                      }
                    ]
                  }
                },
                "required": [
                  "field",
                  "op"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "and": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 10,
                    "items": {
                      "type": "object",
                      "description": "Recursive OpenAPI schema reference #/components/schemas/FilterExpression.",
                      "additionalProperties": true
                    }
                  }
                },
                "required": [
                  "and"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "or": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 10,
                    "items": {
                      "type": "object",
                      "description": "Recursive OpenAPI schema reference #/components/schemas/FilterExpression.",
                      "additionalProperties": true
                    }
                  }
                },
                "required": [
                  "or"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "not": {
                    "type": "object",
                    "description": "Recursive OpenAPI schema reference #/components/schemas/FilterExpression.",
                    "additionalProperties": true
                  }
                },
                "required": [
                  "not"
                ],
                "additionalProperties": false
              }
            ]
          },
          "group_by": {
            "type": "array",
            "maxItems": 5,
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "join": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "object",
              "properties": {
                "on": {
                  "type": "object",
                  "properties": {
                    "left": {
                      "type": "string",
                      "minLength": 1
                    },
                    "right": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "required": [
                    "left",
                    "right"
                  ],
                  "additionalProperties": false
                },
                "table": {
                  "type": "string",
                  "minLength": 1
                },
                "type": {
                  "type": "string",
                  "default": "inner",
                  "enum": [
                    "inner",
                    "left"
                  ]
                }
              },
              "required": [
                "table",
                "on"
              ],
              "additionalProperties": false
            }
          },
          "order_by": {
            "type": "array",
            "description": "Custom sort. Queries with a custom order_by do not support cursor pagination.",
            "maxItems": 3,
            "items": {
              "type": "object",
              "properties": {
                "direction": {
                  "type": "string",
                  "default": "asc",
                  "enum": [
                    "asc",
                    "desc"
                  ]
                },
                "field": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "field"
              ],
              "additionalProperties": false
            }
          },
          "select": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "as": {
                      "type": "string",
                      "minLength": 1
                    },
                    "field": {
                      "type": "string",
                      "minLength": 1
                    },
                    "fn": {
                      "type": "string",
                      "enum": [
                        "count",
                        "sum",
                        "avg",
                        "max",
                        "min"
                      ]
                    },
                    "path": {
                      "type": "array",
                      "minItems": 1,
                      "maxItems": 5,
                      "items": {
                        "type": "string",
                        "minLength": 1
                      }
                    }
                  },
                  "required": [
                    "fn",
                    "field",
                    "as"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "as": {
                      "type": "string"
                    },
                    "field": {
                      "type": "string",
                      "minLength": 1
                    },
                    "path": {
                      "type": "array",
                      "minItems": 1,
                      "maxItems": 5,
                      "items": {
                        "type": "string",
                        "minLength": 1
                      }
                    },
                    "table": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "field"
                  ],
                  "additionalProperties": false
                }
              ]
            }
          },
          "tables": {
            "type": "array",
            "minItems": 1,
            "maxItems": 5,
            "items": {
              "type": "object",
              "properties": {
                "alias": {
                  "type": "string"
                },
                "id": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "id"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "tables"
        ],
        "additionalProperties": false
      }
    },
    "required": [
      "query"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Output reference

Standard tool result payload.

| Name                 | Type     | Required | Default | Details                                        |
| -------------------- | -------- | -------- | ------- | ---------------------------------------------- |
| `result.data`        | `object` | Yes      | —       | Provider response payload.                     |
| `result.data.cursor` | `string` | No       | —       | —                                              |
| `result.data.data`   | `array`  | Yes      | —       | —                                              |
| `result.data.fields` | `record` | No       | —       | —                                              |
| `result.meta`        | `object` | No       | —       | Additional response metadata (status, paging). |

<details>
  <summary>Show raw output schema</summary>

  ### Output JSON Schema

  ```json theme={null}
  {
    "type": "object",
    "description": "Standard tool result payload.",
    "properties": {
      "data": {
        "type": "object",
        "description": "Provider response payload.",
        "properties": {
          "cursor": {
            "type": "string"
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "fields": {
                        "type": [
                          "object",
                          "null"
                        ],
                        "additionalProperties": {}
                      },
                      "is_stale": {
                        "type": "boolean",
                        "const": true
                      },
                      "status": {
                        "type": "string",
                        "const": "success"
                      },
                      "value": {}
                    },
                    "required": [
                      "status",
                      "fields"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "error": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string",
                        "const": "error"
                      }
                    },
                    "required": [
                      "status"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "status": {
                        "type": "string",
                        "enum": [
                          "running",
                          "queued",
                          "retry",
                          "rate_limited",
                          "awaiting_callback"
                        ]
                      }
                    },
                    "required": [
                      "status"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "status": {
                        "type": "string",
                        "const": "empty"
                      }
                    },
                    "required": [
                      "status"
                    ],
                    "additionalProperties": false
                  }
                ]
              }
            }
          },
          "fields": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name",
                "type"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "data"
        ],
        "additionalProperties": false
      },
      "meta": {
        "type": "object",
        "description": "Additional response metadata (status, paging).",
        "additionalProperties": true
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Deepline cost

* Pricing model: `fixed` (per call).
* Estimated Deepline credits: `0` per pricing unit.
* Provider-native pricing may still exist outside Deepline credit billing.

## Related documentation

* [Clay Enterprise provider guide](/docs/providers/clay/guide)
* [SDK V2 quickstart](/docs/sdk-v2/quickstart)
* [SDK reference](/docs/sdk-v2/sdk-reference)
* [Run tools across a CSV](/docs/sdk-v2/batch-csv)