SDKs

Overview

Retell provides official SDKs for Node.js and Python to simplify integration with our platform. While you can use our REST API directly, our SDKs offer:

Type safety: Full TypeScript support with autocomplete
Simplified authentication: Built-in API key handling
Error handling: Structured error responses with detailed messages
Reduced boilerplate: Cleaner, more maintainable code

Available SDKs & Requirements

Node.js TypeScript SDK

Package: retell-sdk on NPM
Requirements: Node.js version 18.10.0 or higher
Features: Full TypeScript support, async/await, promise-based API

Python SDK

Package: retell-sdk on PyPI
Requirements: Python 3.9 or higher
Features: Type hints, async support, comprehensive error handling

Get Your API Key

Navigate to the “API Keys” tab in your dashboard to obtain your API key.

API Keys tab in Retell dashboard showing where to find and copy your API key

Install the SDK

Choose your preferred language and install the SDK:

npm i retell-sdk

pip install retell-sdk

Initialize the Client

Create a new client instance using your API key:

import Retell from 'retell-sdk';

const retellClient = new Retell({
  apiKey: "YOUR_API_KEY",
});

from retell import Retell

retell_client = Retell(
  api_key="YOUR_API_KEY"
)

Make API Calls

Here’s an example of making a phone call using the SDK:

try {
  const response = await retellClient.call.createPhoneCall({
    from_number: '+14157774444',
    to_number: '+12137774445',
  });
  console.log('Call initiated:', response);
} catch (error) {
  console.error('Error making call:', error);
}

try:
  response = retell_client.call.create_phone_call(
    from_number="+14157774444",
    to_number="+12137774445"
  )
  print(f"Call initiated: {response}")
except Exception as e:
  print(f"Error making call: {e}")

SDK vs REST API Comparison

To illustrate the benefits of using our SDK, here’s a comparison of creating an agent using both methods:

Using REST API (More Verbose)

const options = {
  method: 'POST',
  headers: {
    Authorization: '<authorization>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    response_engine: {
      type: 'retell-llm',
      llm_id: 'llm_234sdertfsdsfsdf'
    },
    agent_name: 'Jarvis',
    voice_id: '11labs-Adrian',
    // ... many more configuration options
  })
};

fetch('https://api.retellai.com/create-agent', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Using SDK (More Concise)

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

async function main() {
  const params: Retell.AgentCreateParams = {
    response_engine: { 
      llm_id: 'llm_234sdertfsdsfsdf',
      type: 'retell-llm'
    },
    voice_id: '11labs-Adrian',
  };
  const agentResponse = await client.agent.create(params);
}

Best Practices

1. Error Handling

Always wrap SDK calls in try-catch blocks to handle potential errors gracefully:

try {
  const response = await retellClient.call.createPhoneCall(params);
  // Handle success
} catch (error) {
  if (error.code === 'insufficient_funds') {
    // Handle specific error
  }
  // Log error details
}

2. Environment Variables

Store your API key securely using environment variables:

const retellClient = new Retell({
  apiKey: process.env.RETELL_API_KEY,
});

3. Type Safety

Leverage TypeScript types for better developer experience:

import { Retell, AgentCreateParams } from 'retell-sdk';

const params: AgentCreateParams = {
  // TypeScript will provide autocomplete here
};

Rate Limits

Limits apply per organization + route, enforced at the HTTP layer.

Endpoint group	Limit
Call creation	1000 / 10s, plus 60 4xx errors / min
List endpoints (`list-`, `batch-get-`)	15 / 10s
All other SDK endpoints (get / create / update / delete)	100 / 10s
LLM / agent playground completions	8 / 2s

Outbound calls are also subject to CPS limits (excess calls are queued, not rejected) and the per-org concurrent call limit.

429 Response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limiter: general
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 7

{ "status": "error", "message": "Too many API requests, you are being throttled, please try again later." }

X-RateLimit-Limiter identifies which limiter fired: general, list, call, call-error, or llm-playground.

Handling 429s

Use RateLimit-Reset (seconds) for backoff; retry with jittered exponential backoff.
Don’t parallelize list-* calls — the per-route budget is small.
For high call volume, design around CPS rather than HTTP throughput.

Get Started

Conductor (AI Assistant)

Build

Test

Deploy

Monitor

Reliability & Debugging

Accounts and Workspace

Integrations

Other Topics

Overview

Available SDKs & Requirements

Node.js TypeScript SDK

Python SDK

SDK vs REST API Comparison

Using REST API (More Verbose)

Using SDK (More Concise)

Best Practices

1. Error Handling

2. Environment Variables

3. Type Safety

Rate Limits

429 Response

Handling 429s

​Overview

​Available SDKs & Requirements

​Node.js TypeScript SDK

​Python SDK

​SDK vs REST API Comparison

​Using REST API (More Verbose)

​Using SDK (More Concise)

​Best Practices

​1. Error Handling

​2. Environment Variables

​3. Type Safety

​Rate Limits

​429 Response

​Handling 429s

Overview

Available SDKs & Requirements

Node.js TypeScript SDK

Python SDK

SDK vs REST API Comparison

Using REST API (More Verbose)

Using SDK (More Concise)

Best Practices

1. Error Handling

2. Environment Variables

3. Type Safety

Rate Limits

429 Response

Handling 429s