> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Cartesia

The Cartesia connector lets your AI agent act in each user's Cartesia account. Each user connects their own Cartesia access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 39 tools.

**Authentication:** Bearer Token
**Categories:** AI, Media
**Tools:** 39: 30 read, 6 write, 3 destructive
**Users sign in with:** Access token
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=CARTESIA)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Cartesia connection

   In **AgentKit > Connections**, create a Cartesia connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'cartesia'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Cartesia:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'cartesia_accents_list',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "cartesia"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Cartesia:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="cartesia_accents_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their Cartesia credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'cartesia_accents_list',
  toolInput: {},
  connector: 'cartesia',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="cartesia_accents_list",
    tool_input={},
    connection_name="cartesia",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `cartesia_accents_list`

List Accents · Read-only

List the accents Cartesia supports, optionally filtered by language, locale, or whether a voice can be localized into them.
Returns accents, each with id, name, language, locale, is_locale_default and is_localizable.
Use this to find a valid accent id for cartesia_voice_update or cartesia_voice_localize (localize needs is_localizable true).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `is_localizable` (`boolean`, optional): Set to true to return only accents a voice can be localized into with cartesia_voice_localize. Example: true
- `language` (`string`, optional): Return only accents of this ISO 639-1 language code. Example: es
- `locale` (`string`, optional): Return only accents of this BCP-47 locale. Example: es-MX

Example input: `{}`

### `cartesia_agent_get`

Get Agent · Read-only

Get one Managed Agent with its complete current configuration.
Returns id, name, description, version, created_at, updated_at and config (instructions, initial_message, audio, model, language, tools, system_tools, turn and other settings).
Use this to read an agent's prompt, voice and model before changing it with cartesia_agent_update. Use cartesia_agent_versions_list for its change history.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `agent_id` (`string`, required): ID of the agent. Get it from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE

Example input: `{"agent_id":"<agent_id>"}`

### `cartesia_agent_models_list`

List Agent Models · Read-only

List the LLMs available to Cartesia Managed Agents, with latency and pricing metadata.
Returns data (each model's id, display_name, provider, description, average_latency_ms and per-million-token pricing), has_more and next_page.
Use this to choose the model_id for cartesia_agent_create or cartesia_agent_update. Use cartesia_models_list for speech (TTS/STT) models.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Pagination cursor: the ID of the first model on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: gpt-5.4-mini
- `limit` (`integer`, optional): Number of models to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last model on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: gpt-5.4-mini

Example input: `{}`

### `cartesia_agent_tool_get`

Get Agent Tool · Read-only

Get one shared agent tool (webhook or client) with its full definition.
Returns id, name, description, type, execution settings, and the webhook api_schema or client parameters; with expand agents, also the agents that use it.
Use this to inspect what a tool does before attaching it to an agent. Use cartesia_agent_tools_list to find tool IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `tool_id` (`string`, required): ID of the agent tool. Get it from cartesia_agent_tools_list. Example: tool_3kD9sVq7XyBn2LmPw4ZcRt
- `expand` (`array`, optional): Extra data to include. The only value is agents, which adds the agents that currently use the tool. Example: ["agents"]

Example input: `{"tool_id":"<tool_id>"}`

### `cartesia_agent_tools_list`

List Agent Tools · Read-only

List the shared webhook and client tools that Managed Agents in your account can call, optionally filtered by type or agent.
Returns data (tools with id, name, description, type and settings), has_more and next_page.
Use this to find a tool ID to reference in an agent's config.tools. Use cartesia_agent_tool_get for one tool's full definition.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `agent_id` (`string`, optional): Return only tools used by this agent, from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
- `ending_before` (`string`, optional): Pagination cursor: the ID of the first tool on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: tool_3kD9sVq7XyBn2LmPw4ZcRt
- `limit` (`integer`, optional): Number of tools to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last tool on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: tool_3kD9sVq7XyBn2LmPw4ZcRt
- `type` (`string`, optional): Return only webhook tools or client tools. Example: webhook. One of: `webhook`, `client`.

Example input: `{}`

### `cartesia_agent_version_get`

Get Agent Version · Read-only

Get one immutable configuration version of an agent.
Returns id, description, created_at, created_by and the complete config of that version.
Use this to compare or restore an older configuration: pass its config to cartesia_agent_update to roll back. Use cartesia_agent_get for the current configuration.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `agent_id` (`string`, required): ID of the agent. Get it from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
- `version_id` (`string`, required): ID of the agent configuration version. Get it from cartesia_agent_versions_list. Example: av_7Hq2mXbK9cLdNfPzR3tWvE

Example input: `{"agent_id":"<agent_id>","version_id":"<version_id>"}`

### `cartesia_agent_versions_list`

List Agent Versions · Read-only

List an agent's configuration history, newest first. Each version is an immutable snapshot of the full configuration.
Returns data (versions with id, description, created_at and created_by), has_more and next_page.
Use this to audit or roll back agent changes. Use cartesia_agent_version_get for one version's full config.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `agent_id` (`string`, required): ID of the agent. Get it from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
- `ending_before` (`string`, optional): Pagination cursor: the ID of the first version on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: av_7Hq2mXbK9cLdNfPzR3tWvE
- `limit` (`integer`, optional): Number of versions to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last version on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: av_7Hq2mXbK9cLdNfPzR3tWvE

Example input: `{"agent_id":"<agent_id>"}`

### `cartesia_agents_list`

List Agents · Read-only

List the Managed Agents in your Cartesia account, optionally searching by name or description.
Returns data (agent summaries with id, name, description and timestamps; full configuration is left out), has_more and next_page.
Use this to find an agent_id. Use cartesia_agent_get for one agent's full configuration.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Pagination cursor: the ID of the first agent on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
- `limit` (`integer`, optional): Number of agents to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `q` (`string`, optional): Text to match against agent name or description. Example: receptionist
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last agent on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE

Example input: `{}`

### `cartesia_call_batch_get`

Get Call Batch · Read-only

Get one outbound call batch and the current status of each recipient.
Returns id, name, agent_id, from_number_id, status, scheduling and concurrency settings, scheduled/dispatched/finished call counts, retry_count, timestamps and recipients.
Use this to track a calling campaign. Use cartesia_calls_list with batch_id for the resulting calls and transcripts.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `batch_id` (`string`, required): ID of the call batch. Get it from cartesia_call_batches_list. Example: batch_8c1d2e3f4a5b

Example input: `{"batch_id":"<batch_id>"}`

### `cartesia_call_batches_list`

List Call Batches · Read-only

List outbound call batches (bulk calling campaigns), optionally for one agent.
Returns data (batches with id, name, agent_id, status, call counts and timestamps), has_more and next_page.
Use this to find a batch_id and see campaign progress. Use cartesia_call_batch_get for per-recipient status and cartesia_calls_list with batch_id for the calls.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `agent_id` (`string`, optional): Return only batches for this agent, from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
- `ending_before` (`string`, optional): Pagination cursor: the ID of the first batch on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: batch_8c1d2e3f4a5b
- `limit` (`integer`, optional): Number of batches to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last batch on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: batch_8c1d2e3f4a5b

Example input: `{}`

### `cartesia_call_get`

Get Call · Read-only

Get one Managed Agent call with its transcript.
Returns id, agent_id, agent_name, agent_version_id, status, start_time, end_time, end_reason, error_message, summary, transcript, telephony_params, dynamic_variables and zdr_enabled.
Use this to read what was said on a call and how it ended. Use cartesia_calls_list to find call IDs and cartesia_metric_results_list for its evaluation scores.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `call_id` (`string`, required): ID of the call. Get it from cartesia_calls_list. Example: call_2b7e4f9a1c0d

Example input: `{"call_id":"<call_id>"}`

### `cartesia_calls_list`

List Calls · Read-only

List the calls of one Managed Agent, or the calls placed for one outbound call batch, optionally in a time range. Pass agent_id or batch_id.
Returns data (calls with id, agent_id, status, start_time, end_time, end_reason, summary and telephony details; transcript when expanded), has_more and next_page.
Use this to review an agent's recent calls. Use cartesia_call_get for one call's full transcript and details.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `agent_id` (`string`, optional): Agent whose calls to list, from cartesia_agents_list. Required unless batch_id is set. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
- `batch_id` (`string`, optional): Outbound call batch whose calls to list, from cartesia_call_batches_list. Required unless agent_id is set. Returns one entry per call attempt, so a retried recipient can appear more than once. Example: batch_8c1d2e3f4a5b
- `ending_before` (`string`, optional): Pagination cursor: the ID of the first call on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: call_2b7e4f9a1c0d
- `expand` (`string`, optional): Set to transcript to include each call's transcript. Transcripts can make the response large. Example: transcript. One of: `transcript`.
- `limit` (`integer`, optional): Number of calls to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `start_time_gte` (`string`, optional): Only calls that started at or after this RFC 3339 timestamp. Example: 2026-10-01T00:00:00Z
- `start_time_lte` (`string`, optional): Only calls that started at or before this RFC 3339 timestamp. Example: 2026-10-21T23:59:59Z
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last call on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: call_2b7e4f9a1c0d

Example input: `{}`

### `cartesia_dataset_files_list`

List Dataset Files · Read-only

List the audio files in a dataset.
Returns data (files with id, filename, size and created_at), has_more and next_page.
Use this to check what a dataset holds before fine-tuning. Use cartesia_file_get for one file's metadata.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dataset_id` (`string`, required): ID of the dataset. Get it from cartesia_datasets_list. Example: dataset_9b2f4e7a1c3d
- `ending_before` (`string`, optional): Pagination cursor: the ID of the first file on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: file_EneDabCuJCpfe5CFi5X12e
- `limit` (`integer`, optional): Number of files to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last file on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: file_EneDabCuJCpfe5CFi5X12e

Example input: `{"dataset_id":"<dataset_id>"}`

### `cartesia_dataset_get`

Get Dataset · Read-only

Get one dataset by ID.
Returns id, name, description and created_at.
Use this to check a dataset's details. Use cartesia_dataset_files_list for the files in it.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dataset_id` (`string`, required): ID of the dataset. Get it from cartesia_datasets_list. Example: dataset_9b2f4e7a1c3d

Example input: `{"dataset_id":"<dataset_id>"}`

### `cartesia_datasets_list`

List Datasets · Read-only

List the datasets in your Cartesia account. Datasets group audio files used to fine-tune voices.
Returns data (datasets with id, name, description and created_at), has_more and next_page.
Use this to find a dataset_id. Use cartesia_dataset_get for one dataset and cartesia_dataset_files_list for its files.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Pagination cursor: the ID of the first dataset on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: dataset_9b2f4e7a1c3d
- `limit` (`integer`, optional): Number of datasets to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last dataset on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: dataset_9b2f4e7a1c3d

Example input: `{}`

### `cartesia_file_get`

Get File · Read-only

Get one uploaded file's metadata (not its content).
Returns id, filename, purpose, size, status, owner_id and created_at.
Use this to check a file's processing status or purpose. Use cartesia_files_list to find file IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `file_id` (`string`, required): ID of the file. Get it from cartesia_files_list or cartesia_dataset_files_list. Example: file_EneDabCuJCpfe5CFi5X12e

Example input: `{"file_id":"<file_id>"}`

### `cartesia_files_list`

List Files · Read-only

List files uploaded to your Cartesia account, optionally by purpose or filename.
Returns data (files with id, filename, purpose, size, status and created_at) and has_more.
Use this to find a file ID, for example an agent background sound or a fine-tune sample. Use cartesia_file_get for one file.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Pagination cursor: the ID of the first file on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: file_EneDabCuJCpfe5CFi5X12e
- `limit` (`integer`, optional): Number of files to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `purpose` (`string`, optional): Return only files uploaded for this purpose: agent_background_sound, fine_tune, tts_generation or voice-clone. Example: fine_tune. One of: `agent_background_sound`, `fine_tune`, `tts_generation`, `voice-clone`.
- `q` (`string`, optional): Return only files whose filename contains this text. Example: intro
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last file on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: file_EneDabCuJCpfe5CFi5X12e

Example input: `{}`

### `cartesia_fine_tune_get`

Get Fine-Tune · Read-only

Get one voice fine-tune by ID.
Returns id, name, description, language, accent, model_id, supported_model_ids, dataset, status and user_errors.
Use this to check whether a fine-tune has finished or failed. Use cartesia_fine_tune_voices_list for the voices it produced.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `fine_tune_id` (`string`, required): ID of the fine-tune. Get it from cartesia_fine_tunes_list. Example: fine_tune_4c7e1a9b2d5f

Example input: `{"fine_tune_id":"<fine_tune_id>"}`

### `cartesia_fine_tune_voices_list`

List Fine-Tune Voices · Read-only

List the voices created by a completed fine-tune.
Returns data (voices with id, name, description, language and created_at), has_more and next_page.
Use this to get the voice IDs a fine-tune produced. Use cartesia_voice_get for one voice's details.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `fine_tune_id` (`string`, required): ID of the fine-tune. Get it from cartesia_fine_tunes_list. Example: fine_tune_4c7e1a9b2d5f
- `ending_before` (`string`, optional): Pagination cursor: the ID of the first voice on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: a0e99841-438c-4a64-b679-ae501e7d6091
- `limit` (`integer`, optional): Number of voices to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last voice on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: a0e99841-438c-4a64-b679-ae501e7d6091

Example input: `{"fine_tune_id":"<fine_tune_id>"}`

### `cartesia_fine_tunes_list`

List Fine-Tunes · Read-only

List the voice fine-tunes in your Cartesia account.
Returns data (fine-tunes with id, name, description, language, model_id, dataset and status), has_more and next_page.
Use this to track fine-tuning jobs. Use cartesia_fine_tune_get for one job and cartesia_fine_tune_voices_list for the voices it produced.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Pagination cursor: the ID of the first fine-tune on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: fine_tune_4c7e1a9b2d5f
- `limit` (`integer`, optional): Number of fine-tunes to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last fine-tune on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: fine_tune_4c7e1a9b2d5f

Example input: `{}`

### `cartesia_metric_get`

Get Metric · Read-only

Get one LLM-as-a-judge metric.
Returns id, name, display_name, the judge prompt and created_at.
Use this to read how a metric scores calls. Use cartesia_metric_results_list for its results.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `metric_id` (`string`, required): ID of the metric. Get it from cartesia_metrics_list. Example: metric_5e8b2c1a9d7f

Example input: `{"metric_id":"<metric_id>"}`

### `cartesia_metric_results_list`

List Metric Results · Read-only

List metric results, the scores LLM-as-a-judge metrics gave to agent calls, filtered by agent, metric, call, deployment or date.
Returns data (results with id, metric, call and agent IDs, the value and created_at), has_more and next_page.
Use this to analyze call quality over time. Use cartesia_call_get to read the call behind a result.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `agent_id` (`string`, optional): Return only results for this agent. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
- `call_id` (`string`, optional): Return only results for this call. Example: call_2b7e4f9a1c0d
- `deployment_id` (`string`, optional): Return only results for this agent deployment. Example: dep_4b8e2a6c1f9d
- `end_date` (`string`, optional): Only results created at or before this RFC 3339 datetime. Example: 2026-10-21T23:59:59Z
- `ending_before` (`string`, optional): Pagination cursor: the ID of the first metric result on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: metric_result_3f9a2c7e1b5d
- `limit` (`integer`, optional): Number of metric results to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `metric_id` (`string`, optional): Return only results of this metric, from cartesia_metrics_list. Example: metric_5e8b2c1a9d7f
- `start_date` (`string`, optional): Only results created at or after this RFC 3339 datetime. Example: 2026-10-01T00:00:00Z
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last metric result on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: metric_result_3f9a2c7e1b5d

Example input: `{}`

### `cartesia_metrics_list`

List Metrics · Read-only

List the LLM-as-a-judge metrics in your account that score agent calls.
Returns data (metrics with id, name, display_name, prompt and created_at), has_more and next_page.
Use this to find a metric_id. Use cartesia_metric_results_list for the scores a metric gave to calls.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Number of metrics to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last metric on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: metric_5e8b2c1a9d7f

Example input: `{}`

### `cartesia_models_list`

List Models · Read-only

List the Sonic text-to-speech and Ink speech-to-text model IDs your Cartesia key can call.
Returns data, an array of models with id, capability (tts or stt) and, for STT models, the supported modes.
Use this to pick a model_id for speech or transcription settings. Use cartesia_agent_models_list for the LLMs that power Managed Agents.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `capability` (`string`, optional): Return only text-to-speech (tts) or speech-to-text (stt) models. Omit to return both. Example: tts. One of: `tts`, `stt`.

Example input: `{}`

### `cartesia_phone_number_get`

Get Phone Number · Read-only

Get one phone number in your Cartesia account.
Returns the number's id, phone number, label, provider type and the agent it routes to.
Use this to check how a number is set up. Use cartesia_phone_numbers_list to find number IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `phone_number_id` (`string`, required): ID of the phone number. Get it from cartesia_phone_numbers_list. Example: pn_7f3a9c2e1b4d

Example input: `{"phone_number_id":"<phone_number_id>"}`

### `cartesia_phone_numbers_list`

List Phone Numbers · Read-only

List the phone numbers in your Cartesia account, optionally filtered by assigned agent, telephony provider or search text.
Returns data (numbers with id, the phone number, label, provider type and assigned agent) and has_more.
Use this to see which number routes to which agent. Use cartesia_phone_number_get for one number's details.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `agent_id` (`string`, optional): Return only numbers assigned to this agent. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
- `ending_before` (`string`, optional): Pagination cursor: the ID of the first phone number on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: pn_7f3a9c2e1b4d
- `limit` (`integer`, optional): Number of phone numbers to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `provider_id` (`string`, optional): Return only numbers from this linked telephony provider account. Example: prov_2d8f1a7c9e3b
- `q` (`string`, optional): Text to match against the phone number, its label or the agent name. Example: +1415
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last phone number on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: pn_7f3a9c2e1b4d
- `type` (`string`, optional): Return only numbers of this provider type: twilio, cartesia or sip_trunk. Example: cartesia. One of: `twilio`, `cartesia`, `sip_trunk`.

Example input: `{}`

### `cartesia_pronunciation_dict_get`

Get Pronunciation Dictionary · Read-only

Get one pronunciation dictionary with its entries.
Returns id, name, description, access, pinned, created_at and items (each word with the pronunciation to use).
Use this to see how a dictionary changes pronunciation. Use cartesia_pronunciation_dicts_list to find dictionary IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dict_id` (`string`, required): ID of the pronunciation dictionary. Get it from cartesia_pronunciation_dicts_list. Example: dict_6a1f3c8e2b9d

Example input: `{"dict_id":"<dict_id>"}`

### `cartesia_pronunciation_dicts_list`

List Pronunciation Dictionaries · Read-only

List the pronunciation dictionaries in your Cartesia account. They tell Cartesia how to say specific words, names or acronyms.
Returns data (dictionaries with id, name, description, access, pinned and created_at), has_more and next_page.
Use this to find a dictionary ID for an agent's config.audio.output.pronunciation_dictionary_id. Use cartesia_pronunciation_dict_get for its entries.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Pagination cursor: the ID of the first dictionary on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: dict_6a1f3c8e2b9d
- `limit` (`integer`, optional): Number of dictionaries to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last dictionary on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: dict_6a1f3c8e2b9d

Example input: `{}`

### `cartesia_voice_get`

Get Voice · Read-only

Get one Cartesia voice by its ID.
Returns the voice's id, name, tagline, description, language, gender, accents, country, is_pro, is_owner, access, status and created_at, plus preview_file_url when expanded.
Use this to check a voice before using it in an agent or updating it. Use cartesia_voices_list to search when you do not have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `voice_id` (`string`, required): ID of the voice. Get it from cartesia_voices_list. Example: a0e99841-438c-4a64-b679-ae501e7d6091
- `expand` (`array`, optional): Extra fields to include. The only value is preview_file_url, which adds a URL to download a short preview clip of each voice (downloading it does not use credits). Example: ["preview_file_url"]

Example input: `{"voice_id":"<voice_id>"}`

### `cartesia_voices_list`

List Voices · Read-only

List or search Cartesia voices, including the public voice library and voices your organization owns.
Returns data (each voice's id, name, tagline, description, language, gender, accents, is_owner, access, status and created_at), has_more and next_page.
Use this to find a voice ID by name, language or gender. Use cartesia_voice_get for one voice you already have the ID of.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ending_before` (`string`, optional): Pagination cursor: the ID of the first voice on the current page. Returns the page that comes before it. Do not combine with starting_after. Example: a0e99841-438c-4a64-b679-ae501e7d6091
- `expand` (`array`, optional): Extra fields to include. The only value is preview_file_url, which adds a URL to download a short preview clip of each voice (downloading it does not use credits). Example: ["preview_file_url"]
- `gender` (`string`, optional): Return only voices with this gender presentation: masculine, feminine or gender_neutral. Example: feminine. One of: `masculine`, `feminine`, `gender_neutral`.
- `include_archived` (`boolean`, optional): Set to true to also return archived voices. Defaults to false. Example: true
- `is_owner` (`boolean`, optional): Set to true to return only voices your organization owns (clones, localized voices). Example: true
- `language` (`string`, optional): Return only voices for a language (en) or a language-locale pair (en-GB). Example: en
- `limit` (`integer`, optional): Number of voices to return per page, from 1 to 100. Cartesia uses 10 when omitted. Example: 20
- `q` (`string`, optional): Text to match against voice name, description or voice ID. Example: narrator
- `starting_after` (`string`, optional): Pagination cursor: the ID of the last voice on the previous page. Returns the page that comes after it. Use the next_page value from the previous response when has_more is true. Do not combine with ending_before. Example: a0e99841-438c-4a64-b679-ae501e7d6091

Example input: `{}`

### `cartesia_agent_create`

Create Agent · Write

Create a Cartesia Managed Agent (a hosted voice agent) and its first configuration version.
Returns the new agent's id, name, description, version and full config.
Use this to set up a new voice agent. Set instructions, voice_id and model_id for a working agent; get IDs from cartesia_voices_list and cartesia_agent_models_list. Use cartesia_agent_update to change an existing agent.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Name shown for the agent. It does not need to be unique. Example: Acme Dental Receptionist
- `config` (`object`, optional): Advanced agent configuration, sent as the config object. Use it for settings not covered by the fields above: audio (input keyterms and noise_suppression; output speed, volume, emotion, pronunciation_dictionary_id and background_sound), model (fallback_strategy, temperature, max_output_tokens), system_tools (end_call, send_dtmf, transfer_to_number), tools (references to tool IDs from cartesia_agent_tools_list), turn (inactivity timeouts), timezone, prompt_optimization, speculative_generation and dynamic_variable_placeholders. The instructions, initial_message, voice_id, model_id and language fields above are merged into this object and win on conflict. Example: {"audio": {"output": {"speed": 1.1}}, "model": {"temperature": 0.4}, "timezone": "America/New_York", "system_tools": {"end_call": {"pre_tool_speech": "auto"}}}
- `description` (`string`, optional): Description of the agent. Example: Books and reschedules dental appointments.
- `initial_message` (`string`, optional): What the agent says when the call starts. Sent as config.initial_message. Example: Hi, thanks for calling Acme Dental. How can I help?
- `instructions` (`string`, optional): System prompt that defines how the agent behaves. Supports dynamic variables such as {{customer_name}}. Sent as config.instructions. Example: You are a friendly receptionist for Acme Dental. Help callers book appointments.
- `language` (`string`, optional): ISO 639-1 code of the language the agent hears and speaks. Sent as config.language.primary. Example: en. One of: `en`, `de`, `pt`, `zh`, `ja`, `fr`, `es`, `hi`, `it`, `ko`, `nl`, `pl`, `ru`, `sv`, `tr`, `tl`, `bg`, `ro`, `ar`, `cs`, `el`, `fi`, `hr`, `ms`, `sk`, `da`, `ta`, `uk`, `hu`, `no`, `vi`, `bn`, `th`, `he`, `ka`, `id`, `te`, `gu`, `kn`, `ml`, `mr`, `pa`, `or`, `ur`.
- `model_id` (`string`, optional): LLM that powers the agent, from cartesia_agent_models_list. Sent as config.model.id. Example: gpt-5.4-mini
- `voice_id` (`string`, optional): Voice the agent speaks with, from cartesia_voices_list. Sent as config.audio.output.voice_id. Example: a0e99841-438c-4a64-b679-ae501e7d6091

Example input: `{"name":"<name>"}`

### `cartesia_agent_update`

Update Agent · Write

Update a Managed Agent's name, description or configuration. Only the fields you set change; any configuration change creates a new immutable version.
Returns the updated agent with its new version and full config.
Use this to change an agent's prompt, voice, model or language. Read the current config first with cartesia_agent_get. To roll back, pass the config of a version from cartesia_agent_version_get.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `agent_id` (`string`, required): ID of the agent to update. Get it from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE
- `config` (`object`, optional): Advanced agent configuration, sent as the config object. Use it for settings not covered by the fields above: audio (input keyterms and noise_suppression; output speed, volume, emotion, pronunciation_dictionary_id and background_sound), model (fallback_strategy, temperature, max_output_tokens), system_tools (end_call, send_dtmf, transfer_to_number), tools (references to tool IDs from cartesia_agent_tools_list), turn (inactivity timeouts), timezone, prompt_optimization, speculative_generation and dynamic_variable_placeholders. The instructions, initial_message, voice_id, model_id and language fields above are merged into this object and win on conflict. Example: {"audio": {"output": {"speed": 1.1}}, "model": {"temperature": 0.4}, "timezone": "America/New_York", "system_tools": {"end_call": {"pre_tool_speech": "auto"}}}
- `description` (`string`, optional): New agent description. Example: Books, moves and cancels dental appointments.
- `initial_message` (`string`, optional): What the agent says when the call starts. Sent as config.initial_message. Example: Hi, thanks for calling Acme Dental. How can I help?
- `instructions` (`string`, optional): System prompt that defines how the agent behaves. Supports dynamic variables such as {{customer_name}}. Sent as config.instructions. Example: You are a friendly receptionist for Acme Dental. Help callers book appointments.
- `language` (`string`, optional): ISO 639-1 code of the language the agent hears and speaks. Sent as config.language.primary. Example: en. One of: `en`, `de`, `pt`, `zh`, `ja`, `fr`, `es`, `hi`, `it`, `ko`, `nl`, `pl`, `ru`, `sv`, `tr`, `tl`, `bg`, `ro`, `ar`, `cs`, `el`, `fi`, `hr`, `ms`, `sk`, `da`, `ta`, `uk`, `hu`, `no`, `vi`, `bn`, `th`, `he`, `ka`, `id`, `te`, `gu`, `kn`, `ml`, `mr`, `pa`, `or`, `ur`.
- `model_id` (`string`, optional): LLM that powers the agent, from cartesia_agent_models_list. Sent as config.model.id. Example: gpt-5.4-mini
- `name` (`string`, optional): New agent name. Example: Acme Dental Receptionist v2
- `version_description` (`string`, optional): Note to attach to the new configuration version. Only allowed when this request changes the configuration. Example: Shorter greeting
- `voice_id` (`string`, optional): Voice the agent speaks with, from cartesia_voices_list. Sent as config.audio.output.voice_id. Example: a0e99841-438c-4a64-b679-ae501e7d6091

Example input: `{"agent_id":"<agent_id>"}`

### `cartesia_dataset_create`

Create Dataset · Write

Create an empty dataset to hold audio files for fine-tuning a voice.
Returns the new dataset's id, name, description and created_at.
Use this as the first step of a fine-tune. Audio files are added outside this connector (file upload is not supported). Use cartesia_dataset_update to rename it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Name for the new dataset. Example: Support voice recordings
- `description` (`string`, optional): Description of the dataset. Sent as an empty string when left empty. Example: Studio recordings of our support voice actor.

Example input: `{"name":"<name>"}`

### `cartesia_dataset_update`

Update Dataset · Write

Replace a dataset's name and description. Both are required; pass the current value for the one you keep.
Returns an empty object on success.
Use this to rename or redescribe a dataset. Read the current values with cartesia_dataset_get first.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dataset_id` (`string`, required): ID of the dataset to update. Get it from cartesia_datasets_list. Example: dataset_9b2f4e7a1c3d
- `description` (`string`, required): New description for the dataset. Example: Cleaned studio recordings of our support voice actor.
- `name` (`string`, required): New name for the dataset. Example: Support voice recordings v2

Example input: `{"dataset_id":"<dataset_id>","description":"<description>","name":"<name>"}`

### `cartesia_voice_localize`

Localize Voice · Write

Create a new voice that sounds like an existing voice speaking natively in another accent. The original voice is not changed.
Returns the new voice's id, name, tagline, description, language, access and created_at.
Use this to get a speaker in another accent or language. Use cartesia_accents_list with is_localizable true to pick the accent. Use cartesia_voice_update to only relabel a voice.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `accent` (`string`, required): Accent to localize into, as an accent id from cartesia_accents_list with is_localizable true. The accent decides the new voice's language. Example: mexican. One of: `australian`, `brazilian-portuguese`, `british`, `bulgarian`, `canadian-french`, `castilian`, `central-tamil`, `central-thai`, `czech`, `danish`, `european-portuguese`, `general-american`, `indian-english`, `indian-urdu`, `israeli`, `istanbul`, `konkani`, `korean`, `mandarin`, `manila`, `mexican`, `modern-standard-arabic`, `north-kerala`, `odia`, `oslo`, `parisian`, `parsi`, `polish`, `powadhi`, `randstad`, `russian`, `slovak`, `southern-karnataka`, `southern-us`, `standard-german`, `standard-hindi`, `standard-indonesian`, `standard-italian`, `standard-japanese`, `stockholm`, `taiwanese-mandarin`, `telangana`.
- `name` (`string`, required): Name for the new localized voice. Example: Support Narrator (Mexican Spanish)
- `voice_id` (`string`, required): ID of the existing voice to localize. Get it from cartesia_voices_list. Example: a0e99841-438c-4a64-b679-ae501e7d6091
- `access` (`string`, optional): Who can use the new voice: private (your organization only) or public. Example: private. One of: `private`, `public`.
- `description` (`string`, optional): Description for the new voice. Example: Mexican Spanish version of our support voice.
- `tagline` (`string`, optional): Short tagline for the new voice, at most 32 characters. Example: Warm and steady

Example input: `{"accent":"australian","name":"<name>","voice_id":"<voice_id>"}`

### `cartesia_voice_update`

Update Voice · Write

Update the name, tagline, description, gender, accent or access of a voice your organization owns. Only the fields you set change.
Returns the updated voice.
Use this to rename or relabel your own voice. Use cartesia_voice_localize to make a new voice in another accent instead of relabeling this one.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `voice_id` (`string`, required): ID of the voice to update (it must be one your organization owns). Get it from cartesia_voices_list with is_owner true. Example: a0e99841-438c-4a64-b679-ae501e7d6091
- `accent` (`string`, optional): Accent label for the voice, as an accent id from cartesia_accents_list. It must be valid for the voice's language. Example: british. One of: `abruzzo-italian`, `african-american`, `african-french`, `arabic-english`, `argentinian`, `australian`, `austrian-german`, `bagheli`, `belgian-dutch`, `belgian-french`, `brazilian-portuguese`, `british`, `budapest`, `bulgarian`, `california`, `camba`, `campania`, `canadian-english`, `canadian-french`, `castilian`, `central-tamil`, `central-thai`, `central-vietnamese`, `chilean`, `colombian`, `czech`, `danish`, `dominican`, `emirati-arabic`, `european-portuguese`, `finnish`, `general-american`, `indian-bengali`, `indian-english`, `indian-urdu`, `irish`, `israeli`, `istanbul`, `jessore`, `khaleeji`, `konkani`, `korean`, `kyiv`, `malay`, `mandarin`, `manila`, `mexican`, `middle-eastern-arabic`, `midwestern-american`, `modern-standard-arabic`, `moldovan`, `new-york`, `new-zealand`, `north-kerala`, `odia`, `oslo`, `panamanian`, `parisian`, `parsi`, `peruvian`, `philippine-english`, `polish`, `powadhi`, `puerto-rican`, `randstad`, `romanian`, `russian`, `singaporean`, `slovak`, `south-african`, `southern-karnataka`, `southern-us`, `southern-vietnamese`, `standard-german`, `standard-hindi`, `standard-indonesian`, `standard-italian`, `standard-japanese`, `stockholm`, `swiss-standard`, `taiwanese-mandarin`, `tbilisi`, `telangana`, `thessaloniki`, `united-states-spanish`, `urdu`, `zagreb`.
- `access` (`string`, optional): Who can use the voice: private (your organization only) or public (any Cartesia user with the voice ID). Example: private. One of: `private`, `public`.
- `description` (`string`, optional): Longer description of the voice. Example: Calm mid-pitch voice for customer support calls.
- `gender` (`string`, optional): Gender presentation label: masculine, feminine or gender_neutral. Leave empty to keep the current value. Example: feminine. One of: `masculine`, `feminine`, `gender_neutral`.
- `name` (`string`, optional): New display name for the voice. Example: Support Narrator
- `tagline` (`string`, optional): A few words describing the voice, at most 32 characters. Example: Warm and steady

Example input: `{"voice_id":"<voice_id>"}`

### `cartesia_agent_delete`

Delete Agent · Destructive

Permanently delete a Managed Agent. Later reads fail and the agent takes no new calls; phone numbers assigned to it stop reaching it.
Returns an empty object on success.
Use this only to remove an agent for good. Use cartesia_agent_update to change an agent instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `agent_id` (`string`, required): ID of the agent to delete. Get it from cartesia_agents_list. Example: agent_Fo7pKNBUwLZxrTd6jvhpaE

Example input: `{"agent_id":"<agent_id>"}`

### `cartesia_dataset_delete`

Delete Dataset · Destructive

Permanently delete a dataset.
Returns an empty object on success.
Use this to remove a dataset you no longer need for fine-tuning. Use cartesia_dataset_update to rename it instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `dataset_id` (`string`, required): ID of the dataset to delete. Get it from cartesia_datasets_list. Example: dataset_9b2f4e7a1c3d

Example input: `{"dataset_id":"<dataset_id>"}`

### `cartesia_voice_delete`

Delete Voice · Destructive

Permanently delete a voice your organization owns. Agents or apps that use this voice ID stop working with it.
Returns an empty object on success.
Use this only to remove your own cloned or localized voices. Use cartesia_voice_update to rename or relabel a voice instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `voice_id` (`string`, required): ID of the voice to delete (it must be one your organization owns). Get it from cartesia_voices_list with is_owner true. Example: a0e99841-438c-4a64-b679-ae501e7d6091

Example input: `{"voice_id":"<voice_id>"}`

## Related

Other AI connectors ([all 216](/agentkit/connectors/?category=ai)):

- [Chorus](/agentkit/connectors/chorus/): Scalekit connector, Username and password, 9 tools
- [Gong](/agentkit/connectors/gong/): Scalekit connector, OAuth, 69 tools
- [Jiminny](/agentkit/connectors/jiminny/): Scalekit connector, Access token, 27 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
