POST /v2/list-calls – Retell AI Retell SDK

Retrieve call details

post/v2/list-calls

Request body

sort_order'ascending' | 'descending'

The calls will be sorted by start_timestamp, whether to return the calls in ascending or descending order.

limitinteger

Limit the number of calls returned. Default 50, Max 1000. To retrieve more than 1000, use pagination_key to continue fetching the next page.

pagination_keystring

The pagination key to continue fetching the next page of calls. Pagination key is represented by a call id here, and it's exclusive (not included in the fetched calls). The last call id from the list calls is usually used as pagination key here. If not set, will start from the beginning.

Example request

{
  "filter_criteria": {
    "call_id": [
      "call_5a82f0a43ea0977566b1104fcfc"
    ],
    "agent_id": [
      "agent_oBeDLoLOeuAbiuaMFXRtDOLriT12345"
    ],
    "call_status": [
      "ended"
    ],
    "call_type": [
      "phone_call"
    ],
    "direction": [
      "inbound"
    ],
    "user_sentiment": [
      "Positive"
    ],
    "call_successful": [
      true
    ],
    "start_timestamp": {
      "upper_threshold": 1738475421000,
      "lower_threshold": 1738475411000
    },
    "metadata.customer_id": [
      "cust_123"
    ],
    "dynamic_variables.user_name": [
      "John"
    ]
  }
}

Response

Successfully retrieved calls.

Example response

[
  {
    "call_type": "web_call",
    "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p",
    "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
    "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
    "agent_name": "My Agent",
    "agent_version": 1,
    "call_status": "registered",
    "retell_llm_dynamic_variables": {
      "customer_name": "John Doe"
    },
    "collected_dynamic_variables": {
      "last_node_name": "Test node"
    },
    "custom_sip_headers": {
      "X-Custom-Header": "Custom Value"
    },
    "data_storage_setting": "everything",
    "opt_in_signed_url": true,
    "start_timestamp": 1703302407333,
    "end_timestamp": 1703302428855,
    "transfer_end_timestamp": 1703302628855,
    "duration_ms": 10000,
    "transcript": "Agent: hi how are you doing?\nUser: Doing pretty well. How are you?\nAgent: That's great to hear! I'm doing well too, thanks! What's up?\nUser: I don't have anything in particular.\nAgent: Got it, just checking in!\nUser: Alright. See you.\nAgent: have a nice day\n",
    "transcript_object": [
      {
        "role": "agent",
        "content": "hi how are you doing?",
        "words": [
          {
            "word": "hi",
            "start": 0.7,
            "end": 1.3
          }
        ]
      }
    ],
    "transcript_with_tool_calls": [
      {
        "role": "agent",
        "content": "hi how are you doing?",
        "words": [
          {
            "word": "hi",
            "start": 0.7,
            "end": 1.3
          }
        ]
      }
    ],
    "scrubbed_transcript_with_tool_calls": [
      {
        "role": "agent",
        "content": "hi how are you doing?",
        "words": [
          {
            "word": "hi",
            "start": 0.7,
            "end": 1.3
          }
        ]
      }
    ],
    "recording_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav",
    "recording_multi_channel_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav",
    "scrubbed_recording_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording.wav",
    "scrubbed_recording_multi_channel_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/recording_multichannel.wav",
    "public_log_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/public_log.txt",
    "knowledge_base_retrieved_contents_url": "https://retellai.s3.us-west-2.amazonaws.com/Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6/kb_retrieved_contents.txt",
    "latency": {
      "e2e": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10
      },
      "asr": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10
      },
      "llm": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10
      },
      "llm_websocket_network_rtt": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10
      },
      "tts": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10
      },
      "knowledge_base": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10
      },
      "s2s": {
        "p50": 800,
        "p90": 1200,
        "p95": 1500,
        "p99": 2500,
        "max": 2700,
        "min": 500,
        "num": 10
      }
    },
    "transfer_destination": "+12137771234",
    "call_analysis": {
      "call_summary": "The agent called the user to ask question about his purchase inquiry. The agent asked several questions regarding his preference and asked if user would like to book an appointment. The user happily agreed and scheduled an appointment next Monday 10am.",
      "user_sentiment": "Positive",
      "call_successful": true
    },
    "call_cost": {
      "product_costs": [
        {
          "product": "elevenlabs_tts",
          "unit_price": 1,
          "cost": 60
        }
      ],
      "total_duration_seconds": 60,
      "total_duration_unit_price": 1,
      "combined_cost": 70
    }
  }
]

Changes

Changed in 13 of the 28 revisions of this API.171224

May 28, 202640402ca870b9421See the full diff
- ▲
  added to the ////////// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the ////////// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the ////////// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the ////////// response property oneOf list for the response status
  response-property-one-of-added
- ●
  added the new no_concurrency_fallback enum value to the ///////// response property for the response status
  response-property-enum-value-added
- ●
  added the new no_concurrency_fallback enum value to the ///////// response property for the response status
  response-property-enum-value-added
- ○
  added the new no_concurrency_fallback enum value to the request property //
  request-property-enum-value-added
May 18, 20266342a99901084See the full diff
- ▲
  added to the ////////// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the ////////// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the ////////// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the ////////// response property oneOf list for the response status
  response-property-one-of-added
May 12, 20266dff2a12f8664See the full diff
- ▲
  the ////////// response's property type changed from no type to string for status
  response-property-type-changed
- ▲
  the ////////// response's property type changed from no type to string for status
  response-property-type-changed
- ▲
  the ////////// response's property type changed from no type to string for status
  response-property-type-changed
- ▲
  the ////////// response's property type changed from no type to string for status
  response-property-type-changed
Apr 28, 20261b4a9d84942a1See the full diff
- ○
  endpoint deprecated
  endpoint-deprecated
Apr 20, 20268ee53928bf3125See the full diff
- ●
  added the new manual_stopped enum value to the ///////// response property for the response status
  response-property-enum-value-added
- ●
  added the new manual_stopped enum value to the ///////// response property for the response status
  response-property-enum-value-added
- ○
  added the new manual_stopped enum value to the request property //
  request-property-enum-value-added
- ○
  added the optional property /////////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property /////////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property /////////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property /////////////// to the response with the status
  response-optional-property-added
Mar 19, 20263aa6f6e028ef1See the full diff
- ○
  added the new optional request property /
  new-optional-request-property
Mar 9, 20268fbf8c54a1423See the full diff
- ▲
  the // request property's minLength was increased from 0 to 1
  request-property-min-length-increased
- ▲
  the // request property's minLength was increased from 0 to 1
  request-property-min-length-increased
- ▲
  the // request property's minLength was increased from 0 to 1
  request-property-min-length-increased
Feb 26, 2026e89903d2c910163See the full diff
- ▲
  removed the enum value registered of the request property //
  request-property-enum-value-removed
- ●
  added the new ivr_reached enum value to the ///////// response property for the response status
  response-property-enum-value-added
- ●
  added the new ivr_reached enum value to the ///////// response property for the response status
  response-property-enum-value-added
- ●
  added the new transfer_bridged enum value to the ///////// response property for the response status
  response-property-enum-value-added
- ●
  added the new transfer_bridged enum value to the ///////// response property for the response status
  response-property-enum-value-added
- ●
  added the new transfer_cancelled enum value to the ///////// response property for the response status
  response-property-enum-value-added
- ●
  added the new transfer_cancelled enum value to the ///////// response property for the response status
  response-property-enum-value-added
- ○
  added the new ivr_reached enum value to the request property //
  request-property-enum-value-added
- ○
  added the new transfer_bridged enum value to the request property //
  request-property-enum-value-added
- ○
  added the new transfer_cancelled enum value to the request property //
  request-property-enum-value-added
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Feb 23, 2026bcff6899fa2a16See the full diff
- ▲
  removed the enum value ivr_reached of the request property //
  request-property-enum-value-removed
- ○
  added the optional property /////////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property /////////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property /////////////// to the response with the status
  response-optional-property-added
- ○
  added the optional property /////////////// to the response with the status
  response-optional-property-added
- ○
  removed the ivr_reached enum value from the ///////// response property for the response status
  response-property-enum-value-removed
- ○
  removed the ivr_reached enum value from the ///////// response property for the response status
  response-property-enum-value-removed
Feb 18, 2026fa273840168321See the full diff
- ●
  added the new ivr_reached enum value to the ///////// response property for the response status
  response-property-enum-value-added
- ●
  added the new ivr_reached enum value to the ///////// response property for the response status
  response-property-enum-value-added
- ○
  added the new ivr_reached enum value to the request property //
  request-property-enum-value-added

Full history (13 revisions)