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

# Clay API reference

> API reference for the Clay plugin in Corsair: every `clay.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Account

### credits

`account.credits`

Get the workspace data credit and action balances

**Risk:** `read`

```ts theme={null}
await corsair.clay.api.account.credits({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `balance` | `number` | Yes | — |
| `action_execution_balance` | `number` | No | — |

***

### me

`account.me`

Get the Clay user and workspace for the API key

**Risk:** `read`

```ts theme={null}
await corsair.clay.api.account.me({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `user` | `object` | Yes | — |
| `workspace` | `object` | Yes | — |

> [accordion] user full type
>
> ```ts theme={null}
> {
>   id: string,
>   name: string | null,
>   email?: string | null,
>   cli_onboarded?: boolean
> }
> ```

> [accordion] workspace full type
>
> ```ts theme={null}
> {
>   id: string,
>   name?: string | null
> }
> ```

***

## Routines

### getResults

`routines.getResults`

Get progress, or the paginated per-item results, of a routine run

**Risk:** `read`

```ts theme={null}
await corsair.clay.api.routines.getResults({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `routine_run_id` | `string` | Yes | — |
| `cursor` | `string` | No | — |
| `limit` | `number` | No | — |

**Output:** `object`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   routine_run_id: string,
>   status: in_progress,
>   total: number,
>   finished: number
> } | {
>   routine_run_id: string,
>   status: string,
>   total: number,
>   finished: number,
>   data: {
>     id: string,
>     status: complete | failed,
>     result?: Record<string, any>,
>     error?: {
>       message: string
>     }
>   }[],
>   cursor?: string
> }
> ```

***

### run

`routines.run`

Run a Clay-managed or custom function routine on 1-100 items; spends credits and returns a routine\_run\_id

**Risk:** `write`

```ts theme={null}
await corsair.clay.api.routines.run({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `routine_id` | `string` | Yes | Routine id, for example function:t\_abc123 |
| `items` | `object[]` | Yes | — |
| `webhook_id` | `string` | No | — |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   id: string,
>   inputs: Record<string, any>
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `routine_run_id` | `string` | Yes | — |
| `status` | `in_progress` | Yes | — |

***

## Search

### create

`search.create`

Create a people or company search over Clay's GTM database from a Clay search query

**Risk:** `write`

```ts theme={null}
await corsair.clay.api.search.create({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | Clay advanced search query; see search.reference |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `search_id` | `string` | Yes | — |
| `source_type` | `people \| companies` | Yes | — |

***

### reference

`search.reference`

Get the Clay search query language reference used by search.create

**Risk:** `read`

```ts theme={null}
await corsair.clay.api.search.reference({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `reference` | `string` | Yes | — |

***

### run

`search.run`

Get the next page of a search's results; each row draws from the workspace search quota

**Risk:** `write`

```ts theme={null}
await corsair.clay.api.search.run({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `search_id` | `string` | Yes | — |
| `limit` | `number` | No | — |

**Output:** `object`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   source_type: people,
>   data: {
>     clay_profile_id: number,
>     name: string | null,
>     first_name: string | null,
>     last_name: string | null,
>     linkedin_url?: string | null,
>     location: {
>       name: string | null,
>       city: string | null,
>       state_or_province: string | null
>     },
>     matched_experiences: {
>       company: string | null,
>       title: string | null,
>       location: string | null,
>       start_date: string | null,
>       end_date: string | null
>     }[]
>   }[],
>   has_more: boolean,
>   exhaustion_reason?: query_limit | no_more_results,
>   period_quota?: {
>     limit: number,
>     used: number,
>     remaining: number,
>     resets_at: string
>   }
> } | {
>   source_type: companies,
>   data: {
>     clay_company_id: number,
>     name: string | null,
>     domain: string | null,
>     size: string | null,
>     type: string | null,
>     country: string | null,
>     industry: string | null,
>     location: string | null,
>     description: string | null,
>     linkedin_url: string | null,
>     annual_revenue: string | null,
>     total_funding_amount_range_usd: number | null
>   }[],
>   has_more: boolean,
>   exhaustion_reason?: query_limit | no_more_results,
>   period_quota?: {
>     limit: number,
>     used: number,
>     remaining: number,
>     resets_at: string
>   }
> }
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.