How To Use Copilot APIs

In this guide, you’ll learn to use Clari Copilot’s REST APIs to access and manage your call data. You’ll also learn how to upload externally recorded calls, such as those from Zoom or Twilio, into Copilot for transcription and analysis.

Copilot APIs allow you to: 

• Search for and download calls, users, and CRM-related data like opportunities and accounts

• Upload call recordings captured outside Clari (e.g. from Twilio or Zoom)

• Access rich analytics, like transcripts, talk-time metrics, and summarize.

For Copilot’s API Reference & Sample Code, click here.

About Copilot REST APIs

Clari Copilot provides a REST API. REST, short for Representational State Transfer, is a set of rules for building APIs that work over the web using simple URLs — like how you visit websites in your browser.

A REST API lets you:

• GET information: e.g., “Give me all the calls from last week”

• POST new data: e.g., “Here’s a new call we recorded on Zoom”

• PUT or PATCH to update something

• DELETE to remove data

What You Can Do with Clari Copilot APIs

Here is a categorized breakdown of key functionalities available via the Clari Copilot API:

🔎 Retrieve Information (GET Requests)

1. List Calls

   • Fetch a paginated list of all recorded calls

   • Apply filters like call status (POST_PROCESSING_DONE), date range, participants

   • Can include metadata like video links and topics
     Endpoint: /calls

2. Get Detailed Call Info

   • Fetch full call details including transcript, summary, and analytics for a specific call_id
     Endpoint: /call-details?id=CALL_ID

3. List Users

   • Retrieve all users in your Copilot workspace (typically reps or team members)
     Endpoint: /users

4. List Topics

   • Get topics discussed in calls with metadata (type, timestamps, scores)
     Endpoints: /topics (basic), /v2/topics (rich)

5. List Accounts and Opportunities

   • Retrieve CRM-related objects linked to Copilot calls for analysis
     Endpoints: /accounts, /opportunities

📤 Upload/Push Data (POST Requests)

1. Upload External Call Recordings

   1. Submit call metadata and audio URLs from tools like Twilio, Zoom, etc.

   2. Triggers processing and generates analytics like transcript and talk ratio
      Endpoint: /create-call

Optional fields include:

1. stereo_to_mono

2. external_transcript

3. header_key / header_value (for secure URL access)

📊 Analytics & Insights (via call-details)

For any uploaded or fetched call, you can extract:

• Transcript: Speaker turns, text, timing

• Talk-time metrics: Duration by speaker

• Summary: High-level overview of what was discussed

• Scoring & Insights: Performance evaluations if enabled

• Associated Topics: Contextual tagging of key themes or questions

🔒 Authentication & Access Control

• Every request requires API Key and Password via headers:

  • X-Api-Key

  • X-Api-Password

• API keys are user-specific and can be rotated in Copilot workspace settings

⏱️ System Behavior & Limits

• Rate limit: 10 requests per second

• Weekly quota: 100,000 requests

• Paginated responses: All list endpoints support limit and skip

🚫 Currently Not Supported via API

These are only available in the UI (or are on the roadmap):

• Battlecards (pre-call notes or playbooks)

• Game Tapes (grouped call snippets)

• Bulk download via a single API call

• Webhooks or real-time push events

Copilot API Use Case Examples

Authentication and Rate Limits

To use the API, you’ll need two things:

• An API Key

• An API Password

You can find them here:

Copilot Web App → Workspace Settings → Integrations → Copilot API

Note: There is only one API key-password combination per organization. Add them as headers to each API request:

curl -H "X-Api-Key:$COPILOT_API_KEY" \ -H "X-Api-Password:$COPILOT_API_PW" \ "<https://rest-api.copilot.clari.com/users>"

Rate Limits

Why this matters:

• If you are looping through a list of 1,000 call IDs and requesting each transcript one by one, that's 1,000 API requests.

• If you are uploading 500 calls, that’s 500 POST requests to /create-call.

The 100,000 requests per week quota refers to the number of times you make an API call, not the number of Copilot calls (recordings) you can retrieve or upload.

You can retrieve or upload many more calls — depending on how efficiently you structure your API usage (e.g., using pagination, batching, or filtering).

Best Practices:

• Use a small delay or a rate limiter in your scripts, so that there is a small pause between retries.

• Only retrieve new calls and not all calls every time to stay within the limit.

📩 Tip: If you think your use case may go beyond this limit, contact your dedicated Clari Support to discuss increasing your quota.

How to Download Transcripts

Download a Transcript for a Single Call

To get a transcript, just call this endpoint with the ID of the call:

Use /call-details with the id of the call.

curl -H "X-Api-Key:$KEY" -H "X-Api-Password:$PW" \
     "<https://rest-api.copilot.clari.com/call-details?id=CALL_ID>"

This returns a JSON transcript with each speaker’s turn, speakerID, start/end times, and spoken text.

Pagination Strategy: Retrieving Large Datasets

When working with large volumes of data (e.g., thousands of calls or users), Clari Copilot API returns results in pages — not all at once. This ensures fast and reliable performance for every request.

How Pagination Works

Most list-based endpoints like /calls or /users support the following parameters:

• limit: How many records you want per page (max: typically 100)

• skip: How many records to skip (used to move to the next page)

Think of it like:

• Page 1 → limit=100&skip=0

• Page 2 → limit=100&skip=100

• Page 3 → limit=100&skip=200
  ...and so on.

Example: Sample code to fetch all calls using pagination

import requests
import os
import time

BASE_URL = "https://rest-api.copilot.clari.com/calls"
HEADERS = {
    "X-Api-Key": os.getenv("KEY"),
    "X-Api-Password": os.getenv("PW")
}

def fetch_all_calls():
    all_calls = []
    skip = 0
    while True:
        params = {
            "limit": 100,
            "skip": skip
        }
        response = requests.get(BASE_URL, headers=HEADERS, params=params)
        response.raise_for_status()
        calls = response.json().get("calls", [])

        if not calls:
            break  # No more data

        all_calls.extend(calls)
        skip += len(calls)
        time.sleep(0.1)  # Stay under 10 req/s

    return all_calls

Where This Applies

You should use this pagination strategy when calling:

• GET /calls – to retrieve all recorded calls

• GET /users – to fetch all team members

• GET /accounts, GET /opportunities – if you’re syncing CRM data

• Any other endpoint that returns a list of objects and supports limit and skip

Pro-tip: Do not hardcode the number of pages to fetch. Instead, stop when the API returns an empty list—that’s a reliable sign you’ve reached the end of the dataset.

Bulk Transcript Export via Script

Clari Copilot does not currently provide a single “bulk export” endpoint for transcripts. However, you can still download all transcripts by using the provided Python script, which:

• Retrieves all your recorded calls in pages

• Fetches the transcript for each call individually

• Writes the data to a .csv file for your use

This script is shared below and is fully functional — you can run it as-is, or adapt it to your environment.

Why We Don't Have a One-Click Bulk Export Endpoint

We’ve designed the API this way for a few practical reasons:

• Performance: Transcripts can be large. A single bulk export could overload the system and affect other users.

• Access Control: Per-call fetching ensures better security and auditability.

• Flexibility: This gives you more control — filter by date, user, or status and build workflows that fit your needs.

So, Can I Export Transcripts in Bulk?

✅ Yes, you absolutely can, by using the script below.
🚫 There is just no one-click API endpoint to get all transcripts at once.

3.3 Example on how to fetch calls and print CSV

Here is a Python script that demonstrates how to fetch calls and print CSV: Calls example

How to Download Call Videos

You can download recorded videos of Copilot calls using the /calls endpoint by enabling the includeVideo=true flag.

STEP 1: Fetch Calls with Video URLs

To get video links, call the /calls endpoint with:

• limit: how many calls to fetch per page (max: 100)

• includeVideo=true: adds a video_url field to each call object

curl -H "X-Api-Key:$KEY" -H "X-Api-Password:$PW" \
     "https://rest-api.copilot.clari.com/calls?limit=100&includeVideo=true"

Each call object will now contain a field:

"video_url": "https://clari-cdn/.../recording.mp4

Note: The video_url is time-limited - typically valid for 4 hours. Download immediately.

STEP 2: Download Videos (example: using wget)

Here's a one-liner to extract and download all videos from a call list:

curl -H "X-Api-Key:$KEY" -H "X-Api-Password:$PW" \
     "https://rest-api.copilot.clari.com/calls?limit=100&includeVideo=true" \
 | jq -r '.calls[].video_url' \
 | while read url; do wget -nv -P videos "$url"; done

Handling Multiple Pages (Pagination)

To download all videos, you'll need to paginate through /calls using limit and skip.

Important Notes

• There is no bulk endpoint to download all videos in one call

• You must paginate through /calls

• URLs expire quickly (~4 hours), download them immediately

• Not all calls may have a video - check call["video_url"] before attempting download

Related Endpoints

There is no single “bulk download” endpoint; you must page through /calls.

Exporting Topics

Clari Copilot surfaces insights through Topics, Battlecards, and Game Tapes. Of these, only Topics are currently accessible via API.

Asset Availability Overview

Understanding Topics: Keyword vs Smart

• Keyword Topics: Basic tags (e.g., "Pricing", "Budget") - available via GET /topics

• Smart Topics: Contextual and AI-extracted themes (e.g., "Timeline discussion", "Competitor objection") - available via GET /v2/topics

To see which topics were mentioned in each specific call, use:

GET /call-details?id=CALL_ID

This will return an array of topics within the call's metadata.

Example: Fetch all Topics

curl -H "X-Api-Key:$KEY" -H "X-Api-Password:$PW" \
     "<https://rest-api.copilot.clari.com/v2/topics>" \
     | jq '.topics[] | {id: .topic_id, name: .topic_name, type: .type}'

Pro-tip: Use filterModifiedGt or filterModifiedLt query parameters to fetch only topics modified within a specific time range.

Integrating External Calls (e.g., Twilio, Zoom, Dialers)

You can use the /create-call endpoint to push externally recorded calls (recordings made outside of Copilot) into the Copilot system for transcription, scoring, and insights — just like any native call.

This is useful if you’re using platforms like:

• Twilio, Zoom, or Aircall to record calls

• Custom dialers or sales tools that store audio files

Required Fields (Minimum)

Here’s an example cURL of what you need to send in your request:

curl -X POST "<https://rest-api.copilot.clari.com/create-call>" \
 -H "X-Api-Key:$KEY" -H "X-Api-Password:$PW" -H "Content-Type: application/json" \
 -d '{
       "source_id":"twilio-abc123",
       "title":"Twilio Demo Call",
       "type":"RECORDING",
       "call_time":"2025-06-01T14:00:00Z",
       "user_emails":["rep@example.com"],
       "audio_url":"<https://api.twilio.com/2010-04-01/Accounts/ACxx/Recordings/REyy.wav>"
     }'

Optional Enhancements:

• header_key / header_value : Use if you're sending a signed URL (e.g., private S3 links)

• external_transcript: Already transcribed the call on your side? You can send it along in the same request.

Handling Stereo Audio: Why stereo_to_mono Matters

"stereo_to_mono": true

Some recording tools (like Zoom or Twilio) store audio in stereo format, where:

• One speaker is recorded in the left channel

• The other is in the right channel

If your recording uses identical audio in both channels, or if Copilot expects a mono stream, this can cause issues like:

• Incorrect transcription

• Missing or incomplete audio

• Difficulty in speaker detection or analytics

✅ Setting stereo_to_mono: true ensures the audio is correctly processed, and both speakers are captured cleanly by combining both channels into one.

Bulk Uploading Calls

While Clari Copilot does not support a single bulk-upload endpoint, you can easily upload calls in bulk by iterating through a list of call records and sending them one at a time to the /create-call endpoint.

This is useful for:

• Migrating historical calls into Copilot

• Uploading large batches of externally recorded conversations (from Zoom, Twilio, etc.)

Recommended Approach

1. Prepare a CSV or JSON file with all the call details
   (one row/object per call)

2. Loop through the list and make individual POST requests to /create-call

Throughput

Clari supports:

• 10 requests per second (rate limit)

• That’s up to 36,000 calls/hour, if paced correctly

Add a small delay (e.g., 0.1 seconds) between calls to stay within limits.

Pro-tip: If you are re-uploading the same call (e.g., during retries or syncs), set force_overwrite_old_call:true

FAQs

1. What counts as a "request" in the weekly quota?

A request is any single interaction with a Copilot API endpoint - whether you are fetching a list of calls, retrieving a transcript, or uploading data. For example, calling GET /calls?limit=100 is one request, even if it returns 100 calls.

Similarly, every POST /create-call to upload an external call counts as one request. The weekly quota of 100,000 refers to these individual API calls - not the number of calls processed or returned.
 

2. What do common error codes mean when using the API?

• 429 Too Many Requests
  You've exceeded the rate limit (10 requests/sec) or a burst capacity. Slow down your request rate and retry after a brief pause.

• 403 Forbidden
  Likely exceeded the weekly quota or your API key lacks necessary access. Check your usage or permissions.

• 400 Bad Request
  The request was malformed—perhaps a required field is missing or has invalid formatting. Double-check your payload against the API spec.

• 500 Internal Server Error
  Indicates a server-side error within Copilot. Try again briefly, and if the issue persists, contact support with your request details.
   

3. Why isn’t there a single “bulk export” endpoint for transcripts or videos?

Retrieving large datasets via a single API call could create performance and stability challenges. Instead, Copilot encourages you to:

• Use pagination to fetch items in manageable batches

• Manage error handling per item (e.g., retries, logging failures)

• Stay within rate limits without impacting overall system performance

This approach offers more control, better reliability, and smoother fault recovery.

4. Can I filter results when fetching assets like calls or topics?

Absolutely! Most list endpoints, including /calls, /users, and /v2/topics, support filtering to help you narrow your results. You can use parameters such as:

• limit and skip for pagination

• filterModifiedGt / filterModifiedLt to fetch recent changes

• Date ranges, user IDs, or status flags (where supported)

Use these parameters to target specific subsets of your data efficiently, saving on quota and improving throughput.

Further Help

• API spec & samples: api-doc.copilot.clari.com/ in the repository.

• Reach out to your dedicated support manager.