Skip to content
Voicebot

List communications

GET
/v1/communication
curl --request GET \
  --url https://example.com/v1/communication \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
<= 500

Page size, max 500 (default 100); a larger value is rejected with 400.

offset
integer
show_deleted
boolean

Include soft-deleted rows when true.

filter_or
string

Comma-separated field names to OR-search via filter_query. Accepted: call_sid (exact, cal_ prefix tolerated), recipient (substring, case-insensitive).

filter_query
string

Search term matched across the fields named in filter_or.

version
integer

Published scenario version the run used.

draft_version
integer

Draft scenario version the run used.

scenario_sid
string

Filter by the scenario recorded on the communication.

agent_sid
string
recipient
string
direction
string
call_sid
string
status
string
call_status
string
strategy_sid
string
is_test
boolean
created_at_from
string format: date-time
created_at_to
string format: date-time
duration_min
integer
duration_max
integer
include
string

Comma-separated related resources to resolve into included. Accepted: agent, scenario, results. An unlisted name is rejected with 400.

Header Parameters

Section titled “Header Parameters”
X-Account-Sid
string

Target account for account-scoped resources. Principals without an account scope (superuser, tenant API key) MUST send it to declare which account to operate in. Account-scoped principals may omit it; if sent it must match their own account or the request is rejected with scope_conflict. For tenant API keys the account must belong to the key’s tenant.

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
object
items
required
Array<object>
object
id
required
string
account_sid
required
string
agent_sid
required
string
scenario_sid
required

Scenario the communication runs; empty on legacy rows created before the scenario binding was recorded.

string
strategy_sid
required
string
nullable
version
required

Published scenario version; null when the run used a draft.

integer
nullable
draft_version
required

Draft scenario version; null when the run used a published version. Exactly one of version / draft_version is set.

integer
nullable
strategy_attempt_sid
required
string
nullable
strategy_attempt_number
required
integer
recipient
required
string
direction
required
string
Allowed values: inbound outbound
communication_status
required
string
Allowed values: new ready dialing in_progress bounced done failed drifted
call_status
required
string
Allowed values: busy rejected no_answer voicemail incomplete completed failed tech_canceled
reason
required
string
data
required
object
key
additional properties
any
variables
required
object
key
additional properties
any
status_history
required
Array<object>
nullable
object
from
required
string
to
required
string
reason
string
call_sid
string
at
required
string format: date-time
scheduled_at
required
string format: date-time
nullable
schedule
required
object
key
additional properties
any
timezone
required
string
next_call_at
required
string format: date-time
call_attempt_number
required
integer
executor_id
required
string
nullable
call_sid
required
string
nullable
duration
required

Call duration in seconds, measured by the execution layer; 0 until the call completes.

integer
is_test
required

Whether this is a test communication.

boolean
consent_granted
required

Whether personal-data recording consent was granted for the call.

boolean
has_recording
required

Whether a stored call recording exists for this communication.

boolean
has_call_history
required

Whether a saved call execution history exists for this communication.

boolean
created_at
required
string format: date-time
updated_at
required
string format: date-time
total
required

Total matching communications, ignoring paging.

integer format: int64
limit
required

Page size applied to this request.

integer
offset
required

Offset applied to this request.

integer
has_more
required

Whether records beyond this page match the query.

boolean
included
required

Related resources resolved for this page, deduplicated. A to-one relation is keyed by the related resource’s own id, so a row resolves it as included.agents[row.agent_sid]. A to-many relation is keyed by the owning row’s id and holds an array, so a row resolves it as included.results[row.id]. A relation’s map is present whenever it was requested, empty if nothing resolved; a reference the caller may not read is simply absent from the map and the row keeps its sid.

object
agents
object
key
additional properties
object
id
required
string
account_sid
required
string
gateway_type
required

Selects the gateway kind; the matching sid (number_sid / number_pool_sid) must be set and the other empty (422 otherwise).

string
Allowed values: number number_pool
number_sid
required
string
nullable
number_pool_sid
required
string
nullable
scenario_sid
required
string
voicemail_enabled
required
boolean
call_recording
required
boolean
calling_schedule
required
object
strategy

Schedule strategy

string
args

Strategy args (free-form)

object
key
additional properties
any
timezone
required
string
limits
required
object
cps
integer
cpl
integer
is_test
required
boolean
communication_result
required
object
targets
Array<object>
object
url
string
sms
required
object
provider_sid
required
string
use_alpha
boolean
alpha

Required when use_alpha is true; one of the provider’s alphas.

string
number

Required when use_alpha is false; one of the provider’s numbers.

string
status
required
string
Allowed values: active inactive
archive_time
required
string format: date-time
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time
scenarios
object
key
additional properties

A scenario as embedded in another resource’s included map: every Scenario field except constructor. The constructor is the entire scenario graph and is unbounded in size, so it would dominate a page that embeds one scenario per row; fetch /v1/scenario/{id} for it.

object
id
required
string
type
required
string
Allowed values: constructor
name
required
string
template
required
string
description
required
string
account_sid
required
string
fix_communication_ttl
required
integer
is_shared_for_copy
required
boolean
created_at
required
string format: date-time
updated_at
required
string format: date-time
version
required
integer
draft_exists
required
boolean
results

Result deliveries per communication id.

object
key
additional properties
Array<object>
object
id
required
string
communication_sid
required
string
account_sid
required
string
target_url
required
string
status
required
string
Allowed values: new in_progress delivered undelivered failed
payload
required
object
key
additional properties
any
attempts
required
integer
next_attempt_at
required
string format: date-time
status_changed_at
required
string format: date-time
last_error
required
string
last_response_status
required
integer
nullable
history
required
Array<object>
nullable
object
at
required
string format: date-time
http_status
integer
error
string
delivered_at
required
string format: date-time
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time
Example
{
  "items": [
    {
      "direction": "inbound",
      "communication_status": "new",
      "call_status": "busy"
    }
  ],
  "included": {
    "agents": {
      "additionalProperty": {
        "gateway_type": "number",
        "status": "active"
      }
    },
    "scenarios": {
      "additionalProperty": {
        "type": "constructor"
      }
    },
    "results": {
      "additionalProperty": [
        {
          "status": "new"
        }
      ]
    }
  }
}

400

Section titled “400”

Invalid request body or parameters

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

401

Section titled “401”

Missing or invalid credentials

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

500

Section titled “500”

Internal server error

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}