> ## Documentation Index > Fetch the complete documentation index at: https://docs.phonely.ai/llms.txt > Use this file to discover all available pages before exploring further. # List calls > One agent's calls, newest first. Pages follow `started_at` (newest first, calls without one last), then `id`. Filters combine with AND; the values of one repeated filter combine with OR. To pick up new calls, poll with `started_from` set a little before your last sync and de-duplicate by `id`: a call's status, outcome and summary can still change after it first appears. ## OpenAPI ````yaml /api-reference/v1/openapi.json get /v1/calls openapi: 3.1.0 info: description: >- Authenticate every request with an org API key: `Authorization: Bearer phk_…`. title: Phonely API version: '1' servers: - description: US url: https://api.us.phonely.ai - description: AU url: https://api.au.phonely.ai security: [] paths: /v1/calls: get: tags: - Calls summary: List calls description: >- One agent's calls, newest first. Pages follow `started_at` (newest first, calls without one last), then `id`. Filters combine with AND; the values of one repeated filter combine with OR. To pick up new calls, poll with `started_from` set a little before your last sync and de-duplicate by `id`: a call's status, outcome and summary can still change after it first appears. operationId: list_calls parameters: - description: The agent whose calls to list. in: query name: agent_id required: true schema: description: The agent whose calls to list. minLength: 1 title: Agent Id type: string - description: >- Only calls in these statuses; repeat for several. Defaults to `completed`, `ended`, `in_progress` and `in_warm_transfer`. in: query name: status required: false schema: anyOf: - items: $ref: '#/components/schemas/CallStatus' type: array - type: 'null' description: >- Only calls in these statuses; repeat for several. Defaults to `completed`, `ended`, `in_progress` and `in_warm_transfer`. title: Status - description: >- Only calls of these types, as a call's `type` reports them; repeat for several. in: query name: type required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Only calls of these types, as a call's `type` reports them; repeat for several. title: Type - description: >- Only calls that started at or after this time (ISO 8601 with a timezone). in: query name: started_from required: false schema: anyOf: - format: date-time type: string - type: 'null' description: >- Only calls that started at or after this time (ISO 8601 with a timezone). title: Started From - description: Only calls that started before this time (ISO 8601 with a timezone). in: query name: started_before required: false schema: anyOf: - format: date-time type: string - type: 'null' description: >- Only calls that started before this time (ISO 8601 with a timezone). title: Started Before - description: >- Only calls that ended for these reasons, as a call's `ended_reason` reports them; repeat for several. in: query name: ended_reason required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Only calls that ended for these reasons, as a call's `ended_reason` reports them; repeat for several. title: Ended Reason - description: >- Only calls with these sentiments, as a call's `sentiment` reports them; repeat for several. in: query name: sentiment required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Only calls with these sentiments, as a call's `sentiment` reports them; repeat for several. title: Sentiment - description: >- Only calls with these outcomes, exactly as a call's `outcome` reports them; repeat for several. in: query name: outcome required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Only calls with these outcomes, exactly as a call's `outcome` reports them; repeat for several. title: Outcome - description: >- Only calls with this customer, exactly as a call's `customer_phone_number` reports it, such as `+14155550123`. Encode the `+` as `%2B` in the URL, or it arrives as a space. in: query name: customer_phone_number required: false schema: anyOf: - minLength: 1 type: string - type: 'null' description: >- Only calls with this customer, exactly as a call's `customer_phone_number` reports it, such as `+14155550123`. Encode the `+` as `%2B` in the URL, or it arrives as a space. title: Customer Phone Number - description: Only calls placed by this campaign. in: query name: campaign_id required: false schema: anyOf: - minLength: 1 type: string - type: 'null' description: Only calls placed by this campaign. title: Campaign Id - description: >- Only calls that lasted at least this long. Like `max_duration_seconds`, it matches only calls with a duration (`duration_seconds` not `null`). in: query name: min_duration_seconds required: false schema: anyOf: - minimum: 0 type: number - type: 'null' description: >- Only calls that lasted at least this long. Like `max_duration_seconds`, it matches only calls with a duration (`duration_seconds` not `null`). title: Min Duration Seconds - description: >- Only calls that lasted at most this long. Like `min_duration_seconds`, it matches only calls with a duration (`duration_seconds` not `null`). in: query name: max_duration_seconds required: false schema: anyOf: - minimum: 0 type: number - type: 'null' description: >- Only calls that lasted at most this long. Like `min_duration_seconds`, it matches only calls with a duration (`duration_seconds` not `null`). title: Max Duration Seconds - description: Calls per page, 1 to 100. in: query name: limit required: false schema: default: 50 description: Calls per page, 1 to 100. maximum: 100 minimum: 1 title: Limit type: integer - description: '`next_cursor` from the previous page.' in: query name: cursor required: false schema: anyOf: - type: string - type: 'null' description: '`next_cursor` from the previous page.' title: Cursor - description: Optional. Must be the key's org. in: header name: Phonely-Organization required: false schema: anyOf: - type: string - type: 'null' description: Optional. Must be the key's org. title: Phonely-Organization responses: '200': content: application/json: schema: $ref: '#/components/schemas/CallList' description: Successful Response headers: Phonely-Organization: description: The authorized organization for this request. schema: type: string '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The request is invalid: a malformed body, a bad or unknown field, or an unknown query parameter. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The API key is missing, invalid or revoked. headers: WWW-Authenticate: description: Always `Bearer`. schema: type: string '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The key can't do this: a read-only key writing, or `Phonely-Organization` naming another org. '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limited. Retry after the number of seconds in `Retry-After`. headers: Retry-After: description: Seconds until the request can be retried. schema: type: integer '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error. Contact support with the request ID. '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Authentication, authorization or another required service is temporarily unavailable. security: - HTTPBearer: [] components: schemas: CallStatus: description: >- Where a call is in its lifecycle, including the outcomes of pay-per-call transfers. Known values: `completed`, `ended`, `in_progress`, `in_warm_transfer`, `queued`, `queueing`, `redial_scheduled`, `cancelled`, `dnc`, `failed`, `transferred_sold`, `transferred_not_sold`, `transferred_pending_sale`, `rev_share_pending_qualification`, `transferred_busy`, `transferred_no_answer`, `transferred_failed`. More can be added, so handle values you don't recognize. title: CallStatus type: string x-extensible-enum: - completed - ended - in_progress - in_warm_transfer - queued - queueing - redial_scheduled - cancelled - dnc - failed - transferred_sold - transferred_not_sold - transferred_pending_sale - rev_share_pending_qualification - transferred_busy - transferred_no_answer - transferred_failed CallList: additionalProperties: false properties: data: description: The items on this page. items: $ref: '#/components/schemas/CallSummary' title: Data type: array next_cursor: anyOf: - type: string - type: 'null' description: Pass as `cursor` to get the next page. `null` on the last page. title: Next Cursor required: - data - next_cursor title: CallList type: object ErrorResponse: additionalProperties: false description: The body of every `/v1` error. properties: error: $ref: '#/components/schemas/Error' description: What went wrong. required: - error title: ErrorResponse type: object CallSummary: additionalProperties: false description: >- A call as the list returns it. `GET /v1/calls/{id}` adds the call analysis. properties: agent_id: description: The agent that handled the call. title: Agent Id type: string business_phone_number: anyOf: - type: string - type: 'null' description: >- The Phonely number on the call, as recorded: usually E.164, such as `+14155550100`. title: Business Phone Number campaign_id: anyOf: - type: string - type: 'null' description: The outbound campaign that placed the call, if any. title: Campaign Id customer_phone_number: anyOf: - type: string - type: 'null' description: >- The customer on the call, as recorded: usually E.164, but `Anonymous` or a SIP address when they withheld their number. `null` for web calls. title: Customer Phone Number duration_seconds: anyOf: - type: number - type: 'null' description: >- How long the call lasted. `null` when not recorded, as for a call that never connected. title: Duration Seconds ended_at: anyOf: - format: date-time type: string - type: 'null' description: When the call ended. `null` while it is still in progress. title: Ended At ended_reason: anyOf: - type: string - type: 'null' description: >- Why the call ended. `null` when it was not recorded. Known values: `assistant_ended_call`, `assistant_forwarded_call`, `customer_ended_call`, `hangup_during_warm_transfer`, `max_duration_reached`, `silence_timeout`, `no_answer`, `user_busy`, `call_failed`, `voicemail`, `no_one_engaged`, `pre_screen_hangup`, `greeting_hangup`, `pre_greeting_hangup`, `greeting_timeout`, `pre_call_rejected`, `pipeline_error`, `unknown_error`, `unsure`. More can be added, so handle values you don't recognize. title: Ended Reason x-extensible-enum: - assistant_ended_call - assistant_forwarded_call - customer_ended_call - hangup_during_warm_transfer - max_duration_reached - silence_timeout - no_answer - user_busy - call_failed - voicemail - no_one_engaged - pre_screen_hangup - greeting_hangup - pre_greeting_hangup - greeting_timeout - pre_call_rejected - pipeline_error - unknown_error - unsure id: description: The call's ID. title: Id type: string object: const: call default: call description: The type of this object, always `call`. title: Object type: string outcome: anyOf: - type: string - type: 'null' description: The call's outcome, as the agent's call analysis labels it. title: Outcome sentiment: anyOf: - type: string - type: 'null' description: >- The customer's sentiment: from call analysis, unless someone changed it in the web app. Known values: `positive`, `negative`, `neutral`, `unsure`. More can be added, so handle values you don't recognize. title: Sentiment x-extensible-enum: - positive - negative - neutral - unsure started_at: anyOf: - format: date-time type: string - type: 'null' description: When the call started, or was queued if it never connected. title: Started At status: description: >- Where the call is in its lifecycle. Known values: `completed`, `ended`, `in_progress`, `in_warm_transfer`, `queued`, `queueing`, `redial_scheduled`, `cancelled`, `dnc`, `failed`, `transferred_sold`, `transferred_not_sold`, `transferred_pending_sale`, `rev_share_pending_qualification`, `transferred_busy`, `transferred_no_answer`, `transferred_failed`. More can be added, so handle values you don't recognize. title: Status type: string x-extensible-enum: - completed - ended - in_progress - in_warm_transfer - queued - queueing - redial_scheduled - cancelled - dnc - failed - transferred_sold - transferred_not_sold - transferred_pending_sale - rev_share_pending_qualification - transferred_busy - transferred_no_answer - transferred_failed summary: anyOf: - type: string - type: 'null' description: A short summary from call analysis. title: Summary type: anyOf: - type: string - type: 'null' description: >- How the call happened. Known values: `inbound_phone_call`, `outbound_phone_call`, `warm_transfer`, `web_call`, `web_chat`, `messaging_session`, `call_and_messaging`, `pay_per_call`, `unknown`. More can be added, so handle values you don't recognize. title: Type x-extensible-enum: - inbound_phone_call - outbound_phone_call - warm_transfer - web_call - web_chat - messaging_session - call_and_messaging - pay_per_call - unknown required: - object - id - agent_id - type - status - ended_reason - business_phone_number - customer_phone_number - started_at - ended_at - duration_seconds - outcome - sentiment - summary - campaign_id title: CallSummary type: object Error: additionalProperties: false properties: code: description: >- What went wrong, stable and machine-readable. Known values: `validation_failed`, `invalid_cursor`, `invalid_api_key`, `invalid_user_token`, `user_unavailable`, `insufficient_access`, `organization_mismatch`, `forbidden`, `not_found`, `method_not_allowed`, `conflict`, `agent_limit_reached`, `agent_too_large`, `sms_setup_required`, `opportunity_analysis_not_set_up`, `precondition_failed`, `payload_too_large`, `unsupported_media_type`, `precondition_required`, `rate_limited`, `internal_error`, `knowledge_processing_failed`, `bad_gateway`, `service_unavailable`, `gateway_timeout`. More can be added, so handle values you don't recognize. title: Code type: string x-extensible-enum: - validation_failed - invalid_cursor - invalid_api_key - invalid_user_token - user_unavailable - insufficient_access - organization_mismatch - forbidden - not_found - method_not_allowed - conflict - agent_limit_reached - agent_too_large - sms_setup_required - opportunity_analysis_not_set_up - precondition_failed - payload_too_large - unsupported_media_type - precondition_required - rate_limited - internal_error - knowledge_processing_failed - bad_gateway - service_unavailable - gateway_timeout details: description: One entry per problem field. Empty when the error has none. items: $ref: '#/components/schemas/ErrorDetail' title: Details type: array message: description: For people. Wording can change; branch on `code`. title: Message type: string request_id: anyOf: - type: string - type: 'null' description: Also in the `X-Request-Id` header. Quote it to support. title: Request Id required: - code - message - details - request_id title: Error type: object ErrorDetail: additionalProperties: false properties: field: description: >- The field the issue is about, as sent: `agent_id`, `limit`. Empty when none. title: Field type: string issue: description: >- What is wrong with the field. Known values: `required`, `unknown_field`, `invalid_json`, `invalid_type`, `invalid_value`, `out_of_range`, `invalid_cursor`, `read_only_field`. More can be added, so handle values you don't recognize. title: Issue type: string x-extensible-enum: - required - unknown_field - invalid_json - invalid_type - invalid_value - out_of_range - invalid_cursor - read_only_field message: description: 'For people: what is wrong with this field.' title: Message type: string required: - field - issue - message title: ErrorDetail type: object securitySchemes: HTTPBearer: description: 'An org API key: `Authorization: Bearer phk_…`' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.