# Last 30 days, with the conversation result
curl -X GET "https://app.talkover.ai/api/v1/calls?include=insight&per_page=50" \
  -H "Authorization: Bearer talq_your_environment_token_here"

// Last 30 days, with the conversation result
const response = await fetch(
  'https://app.talkover.ai/api/v1/calls?include=insight&per_page=50',
  { headers: { Authorization: 'Bearer talq_your_environment_token_here' } }
);

const { data, pagination } = await response.json();

{
  "success": true,
  "data": [
    {
      "id": "01a0c5a5-390e-710a-a3aa-cab502215d09",
      "to": "+14155550100",
      "to_formatted": "(415) 555-0100",
      "from": "+14155550199",
      "from_formatted": "(415) 555-0199",
      "is_testing": false,
      "direction": "outbound",
      "source": "crm",
      "status": "completed",
      "price": 0.32,
      "start_time": "2026-09-21T20:25:45.000000Z",
      "end_time": "2026-09-21T20:26:49.000000Z",
      "context": { "customer_id": "C-1042" },
      "agent": {
        "id": "019ee647-1c5b-730d-b5dd-c6b3b3005f2d",
        "name": "Ana"
      },
      "insight": {
        "analysis_status": "completed",
        "duration": 64,
        "human_detected": true,
        "objective_achieved": false,
        "call_result": "partial_contact",
        "collected_data": {
          "intent": null,
          "agreed_amount": null
        },
        "campaign_id": "019ea766-4f99-731a-ad31-d99ac48d4812"
      },
      "created_at": "2026-09-21T20:25:40.000000Z",
      "updated_at": "2026-09-21T20:27:02.000000Z"
    },
    {
      "id": "01a0c5a4-8c1e-7f02-9b7e-2f649015d964",
      "to": "+14155550123",
      "to_formatted": "(415) 555-0123",
      "from": "+14155550199",
      "from_formatted": "(415) 555-0199",
      "is_testing": false,
      "direction": "outbound",
      "source": null,
      "status": "voicemail",
      "price": 0.05,
      "start_time": "2026-09-21T20:30:31.000000Z",
      "end_time": "2026-09-21T20:30:49.000000Z",
      "context": {},
      "agent": {
        "id": "019ee647-1c5b-730d-b5dd-c6b3b3005f2d",
        "name": "Ana"
      },
      "insight": {
        "analysis_status": "pending",
        "duration": null,
        "human_detected": null,
        "objective_achieved": null,
        "call_result": null,
        "collected_data": null,
        "campaign_id": "019ea766-4f99-731a-ad31-d99ac48d4812"
      },
      "created_at": "2026-09-21T20:30:20.000000Z",
      "updated_at": "2026-09-21T20:30:49.000000Z"
    }
  ],
  "pagination": {
    "per_page": 50,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0yMSAyMDoyNTo0MCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": null,
    "next_page_url": "https://app.talkover.ai/api/v1/calls?include=insight&per_page=50&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0yMSAyMDoyNTo0MCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_page_url": null
  }
}

GET

api

calls

# Last 30 days, with the conversation result
curl -X GET "https://app.talkover.ai/api/v1/calls?include=insight&per_page=50" \
  -H "Authorization: Bearer talq_your_environment_token_here"

// Last 30 days, with the conversation result
const response = await fetch(
  'https://app.talkover.ai/api/v1/calls?include=insight&per_page=50',
  { headers: { Authorization: 'Bearer talq_your_environment_token_here' } }
);

const { data, pagination } = await response.json();

{
  "success": true,
  "data": [
    {
      "id": "01a0c5a5-390e-710a-a3aa-cab502215d09",
      "to": "+14155550100",
      "to_formatted": "(415) 555-0100",
      "from": "+14155550199",
      "from_formatted": "(415) 555-0199",
      "is_testing": false,
      "direction": "outbound",
      "source": "crm",
      "status": "completed",
      "price": 0.32,
      "start_time": "2026-09-21T20:25:45.000000Z",
      "end_time": "2026-09-21T20:26:49.000000Z",
      "context": { "customer_id": "C-1042" },
      "agent": {
        "id": "019ee647-1c5b-730d-b5dd-c6b3b3005f2d",
        "name": "Ana"
      },
      "insight": {
        "analysis_status": "completed",
        "duration": 64,
        "human_detected": true,
        "objective_achieved": false,
        "call_result": "partial_contact",
        "collected_data": {
          "intent": null,
          "agreed_amount": null
        },
        "campaign_id": "019ea766-4f99-731a-ad31-d99ac48d4812"
      },
      "created_at": "2026-09-21T20:25:40.000000Z",
      "updated_at": "2026-09-21T20:27:02.000000Z"
    },
    {
      "id": "01a0c5a4-8c1e-7f02-9b7e-2f649015d964",
      "to": "+14155550123",
      "to_formatted": "(415) 555-0123",
      "from": "+14155550199",
      "from_formatted": "(415) 555-0199",
      "is_testing": false,
      "direction": "outbound",
      "source": null,
      "status": "voicemail",
      "price": 0.05,
      "start_time": "2026-09-21T20:30:31.000000Z",
      "end_time": "2026-09-21T20:30:49.000000Z",
      "context": {},
      "agent": {
        "id": "019ee647-1c5b-730d-b5dd-c6b3b3005f2d",
        "name": "Ana"
      },
      "insight": {
        "analysis_status": "pending",
        "duration": null,
        "human_detected": null,
        "objective_achieved": null,
        "call_result": null,
        "collected_data": null,
        "campaign_id": "019ea766-4f99-731a-ad31-d99ac48d4812"
      },
      "created_at": "2026-09-21T20:30:20.000000Z",
      "updated_at": "2026-09-21T20:30:49.000000Z"
    }
  ],
  "pagination": {
    "per_page": 50,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0yMSAyMDoyNTo0MCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": null,
    "next_page_url": "https://app.talkover.ai/api/v1/calls?include=insight&per_page=50&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0yMSAyMDoyNTo0MCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_page_url": null
  }
}

List calls

Returns the calls of the authenticated environment, newest first, with filters by status, direction, agent, date and phone number. Pass include=insight to get the conversation result on each call.

Endpoint

GET /api/v1/calls

Request headers

string

required

Bearer token. Format: Bearer talq_your_environment_token_here

Query parameters

string

Adds the conversation result to each call as an insight object. Only accepted value: insight. Any other value, or an array (include[]=insight), returns 422. See The insight block.

string

Filter by call status. Options: completed, canceled, no-answer, busy, failed, voicemail, in-progress.

string

Filter by call direction. Options: inbound, outbound.

string

Only calls of this agent.

string

Start of the period, by created_at. Format YYYY-MM-DD. Default: 30 days ago.

string

End of the period, inclusive. Format YYYY-MM-DD.

string

Prefix of the to or from number, or an exact call id. At least 3 characters; shorter values are ignored.

integer

Items per page. Between 1 and 100. Default: 20.

string

Cursor of the page to fetch, as returned in pagination.next_cursor or pagination.prev_cursor.

Example requests

# Last 30 days, with the conversation result
curl -X GET "https://app.talkover.ai/api/v1/calls?include=insight&per_page=50" \
  -H "Authorization: Bearer talq_your_environment_token_here"

// Last 30 days, with the conversation result
const response = await fetch(
  'https://app.talkover.ai/api/v1/calls?include=insight&per_page=50',
  { headers: { Authorization: 'Bearer talq_your_environment_token_here' } }
);

const { data, pagination } = await response.json();

# Reconcile one day of a campaign's agent
curl -X GET "https://app.talkover.ai/api/v1/calls?include=insight&agent_id=019ee647-1c5b-730d-b5dd-c6b3b3005f2d&date_from=2026-09-21&date_to=2026-09-21&per_page=100" \
  -H "Authorization: Bearer talq_your_environment_token_here"

// Reconcile one day of a campaign's agent, following the cursor
const base = 'https://app.talkover.ai/api/v1/calls?include=insight&agent_id=019ee647-1c5b-730d-b5dd-c6b3b3005f2d&date_from=2026-09-21&date_to=2026-09-21&per_page=100';
const headers = { Authorization: 'Bearer talq_your_environment_token_here' };

let url = base;
while (url) {
  const { data, pagination } = await (await fetch(url, { headers })).json();
  // ...process data
  url = pagination.next_cursor ? `${base}&cursor=${pagination.next_cursor}` : null;
}

# Outbound calls to a number prefix
curl -X GET "https://app.talkover.ai/api/v1/calls?search=%2B1415&direction=outbound" \
  -H "Authorization: Bearer talq_your_environment_token_here"

// Outbound calls to a number prefix
const response = await fetch(
  'https://app.talkover.ai/api/v1/calls?search=%2B1415&direction=outbound',
  { headers: { Authorization: 'Bearer talq_your_environment_token_here' } }
);

Response

Success response (200 OK)

The example below was requested with include=insight. Without it, the insight key is absent.

{
  "success": true,
  "data": [
    {
      "id": "01a0c5a5-390e-710a-a3aa-cab502215d09",
      "to": "+14155550100",
      "to_formatted": "(415) 555-0100",
      "from": "+14155550199",
      "from_formatted": "(415) 555-0199",
      "is_testing": false,
      "direction": "outbound",
      "source": "crm",
      "status": "completed",
      "price": 0.32,
      "start_time": "2026-09-21T20:25:45.000000Z",
      "end_time": "2026-09-21T20:26:49.000000Z",
      "context": { "customer_id": "C-1042" },
      "agent": {
        "id": "019ee647-1c5b-730d-b5dd-c6b3b3005f2d",
        "name": "Ana"
      },
      "insight": {
        "analysis_status": "completed",
        "duration": 64,
        "human_detected": true,
        "objective_achieved": false,
        "call_result": "partial_contact",
        "collected_data": {
          "intent": null,
          "agreed_amount": null
        },
        "campaign_id": "019ea766-4f99-731a-ad31-d99ac48d4812"
      },
      "created_at": "2026-09-21T20:25:40.000000Z",
      "updated_at": "2026-09-21T20:27:02.000000Z"
    },
    {
      "id": "01a0c5a4-8c1e-7f02-9b7e-2f649015d964",
      "to": "+14155550123",
      "to_formatted": "(415) 555-0123",
      "from": "+14155550199",
      "from_formatted": "(415) 555-0199",
      "is_testing": false,
      "direction": "outbound",
      "source": null,
      "status": "voicemail",
      "price": 0.05,
      "start_time": "2026-09-21T20:30:31.000000Z",
      "end_time": "2026-09-21T20:30:49.000000Z",
      "context": {},
      "agent": {
        "id": "019ee647-1c5b-730d-b5dd-c6b3b3005f2d",
        "name": "Ana"
      },
      "insight": {
        "analysis_status": "pending",
        "duration": null,
        "human_detected": null,
        "objective_achieved": null,
        "call_result": null,
        "collected_data": null,
        "campaign_id": "019ea766-4f99-731a-ad31-d99ac48d4812"
      },
      "created_at": "2026-09-21T20:30:20.000000Z",
      "updated_at": "2026-09-21T20:30:49.000000Z"
    }
  ],
  "pagination": {
    "per_page": 50,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0yMSAyMDoyNTo0MCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": null,
    "next_page_url": "https://app.talkover.ai/api/v1/calls?include=insight&per_page=50&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0yMSAyMDoyNTo0MCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_page_url": null
  }
}

Response fields

boolean

required

Whether the request succeeded.

array

required

Array of call objects.

Show Call object

string

required

Unique identifier of the call. Use it for every correlation, including the webhook events.

string

required

Destination number in E.164 format.

string

required

Destination number formatted for display.

string

required

Source number in E.164 format.

string

required

Source number formatted for display.

boolean

required

Whether this is a test call.

string

required

Options: inbound, outbound.

string | null

required

Label you passed as source when creating the call, or null. Not interpreted by Talkover.

string

required

Current status. Terminal values: completed, canceled, no-answer, busy, failed, voicemail. A call still in flight shows initiated, ringing, queued or in-progress.

number

required

Price of the call in the environment’s currency. 0 while the call has not been priced.

string | null

required

ISO 8601 timestamp when the call was answered.

string | null

required

ISO 8601 timestamp when the call ended.

object

required

The context you passed when creating the call. {} when none.

object

required

Show Agent object

string

required

Agent identifier.

string

required

Agent name.

object

Conversation result. Present only with include=insight. See The insight block.

string

required

ISO 8601 timestamp when the call was created.

string

required

ISO 8601 timestamp of the last update.

object

required

Cursor pagination. There is no total count.

Show Pagination object

integer

required

Items per page.

string | null

required

Cursor of the next page. null on the last page.

string | null

required

Cursor of the previous page. null on the first page.

string | null

required

Full URL of the next page, with the same filters.

string | null

required

Full URL of the previous page.

The `insight` block

What the agent captured in the conversation. Same data the event_call_report webhook delivers, available on demand for a whole page of calls. summary and transcript are not here because of their size; read them with Get call insight.

string

required

State of the post-call analysis. Options: completed, pending, unavailable. The analysis runs after the call ends; pending means “query again later”, unavailable means “there will be no result”. Full rules in Get call insight.

integer | null

required

Call duration in seconds. Present in every state. null when no talk time was measured (voicemail, no-answer, failed, busy).

boolean | null

required

A person answered.

boolean | null

required

The objective configured on the agent was reached.

string | null

required

Options: success, partial_contact, unsuccessful.

object | null

required

The fields your agent is configured to collect, with the values extracted from the conversation. The keys are yours. {} when nothing was collected.

string | null

required

Campaign that originated the dial. null outside a campaign. Each retry is its own call.

human_detected, objective_achieved, call_result and collected_data are null whenever analysis_status is not completed. A false there is a real result, never a missing analysis.

Error responses

401 Unauthorized

{
  "message": "Unauthenticated."
}

422 Validation error

Returned for an unknown include, an invalid status or direction, or a date outside YYYY-MM-DD.

{
  "success": false,
  "message": "Invalid include value. Allowed: insight.",
  "error": "Invalid include value. Allowed: insight."
}

Notes

Reconciling a day. Query with include=insight, date_from and date_to at least 30 minutes after the last call ended. By then analysis_status is completed or unavailable for every call, and pending is gone.

Default window. Without date_from, only the last 30 days are returned.

Not in this response. The telephony provider’s call SID and internal routing flags are deliberately excluded. Recordings are served by GET /api/v1/calls/{call_id}/recording-url, which answers 404 when there is none.

Get call insight: GET /api/v1/calls/{call_id}/insight — summary and transcript of one call.
Get agent calls: GET /api/v1/agents/{agent_id}/calls
Get recording URL: GET /api/v1/calls/{call_id}/recording-url
Make a call: POST /api/v1/agents/{agent_id}/call

Get Started

Concepts

API Reference

Guides

List calls

List calls

Endpoint

Request headers

Query parameters

Example requests

Response

Success response (200 OK)

Response fields

The `insight` block

Error responses

401 Unauthorized

422 Validation error

Notes

​List calls

​Endpoint

​Request headers

​Query parameters

​Example requests

​Response

​Success response (200 OK)

​Response fields

​The insight block

​Error responses

​401 Unauthorized

​422 Validation error

​Notes

​Related endpoints

List calls

Endpoint

Request headers

Query parameters

Example requests

Response

Success response (200 OK)

Response fields

The `insight` block

Error responses

401 Unauthorized

422 Validation error

Notes

Related endpoints