> ## Documentation Index > Fetch the complete documentation index at: https://docs.powerdialer.ai/llms.txt > Use this file to discover all available pages before exploring further. # List calls > Read call history for a bounded time interval, optionally narrowed to a calling list or rep. Requires `calls:read`. `from` is inclusive and `to` exclusive; both are ISO timestamps with offsets, and the increasing interval must be at most 366 days. List attribution follows the original call session. Results respect the key's workspace and owner restrictions. Follow `nextCursor` using `after`; pages are ordered by numeric row ID. Later evidence or disposition updates do not reappear just because you advance this cursor, so use change events for reconciliation. Historical rows without established attribution remain unavailable. `recordings:read` and `transcripts:read` independently unlock evidence; otherwise those fields say `restricted`. `400 invalid_request` requires corrected dates/pagination, `403 invalid_owner` requires an allowed rep, and `404 not_found` can indicate an inaccessible list filter. This read is safe to retry without an idempotency key. See [calls and evidence](/guides/call-evidence). ## OpenAPI ````yaml /api/openapi.json get /calls openapi: 3.1.0 info: title: PowerDialer API v2 version: 2.0.0 description: >- Connect your CRM, sales workspace or reporting tools to PowerDialer using scoped API keys. Manage contacts and calling lists, read call evidence and analytics, and receive signed events. All example records and IDs are synthetic; replace them with values from your workspace. Shared-key v1 is retired. API availability was verified on 2026-10-08; see /availability for historical data coverage. Legacy outbound webhooks use a separate contract. servers: - url: https://api.migration.powerdialer.ai/api/public/v2 description: Production API v2; availability verified on 2026-10-08. security: - ApiKey: [] tags: - name: Authentication - name: Contacts - name: Calling lists - name: Imports - name: Calls - name: Synchronization - name: Analytics - name: Webhooks - name: Webhook deliveries - name: Incoming webhook payloads paths: /calls: get: tags: - Calls summary: List calls description: >- Read call history for a bounded time interval, optionally narrowed to a calling list or rep. Requires `calls:read`. `from` is inclusive and `to` exclusive; both are ISO timestamps with offsets, and the increasing interval must be at most 366 days. List attribution follows the original call session. Results respect the key's workspace and owner restrictions. Follow `nextCursor` using `after`; pages are ordered by numeric row ID. Later evidence or disposition updates do not reappear just because you advance this cursor, so use change events for reconciliation. Historical rows without established attribution remain unavailable. `recordings:read` and `transcripts:read` independently unlock evidence; otherwise those fields say `restricted`. `400 invalid_request` requires corrected dates/pagination, `403 invalid_owner` requires an allowed rep, and `404 not_found` can indicate an inaccessible list filter. This read is safe to retry without an idempotency key. See [calls and evidence](/guides/call-evidence). operationId: getCalls parameters: - name: after in: query required: false schema: type: integer minimum: 0 maximum: 2147483647 default: 0 description: >- Exclusive numeric ID cursor. Omit or use 0 for the first page, then pass the previous nextCursor. Keep the same filters while paging. example: 0 - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 200 default: 50 description: >- Maximum items to return in one page, from 1 to 200. Defaults to 50. Smaller pages reduce response size; this is not a total-result limit. example: 50 - name: from in: query required: true schema: type: string format: date-time description: >- Inclusive start instant with an explicit UTC offset. Calls are selected by creation time; the interval ending at to must be increasing and no longer than 366 days. example: '2026-10-01T00:00:00Z' - name: to in: query required: true schema: type: string format: date-time description: >- Exclusive end instant with an explicit UTC offset. Use the next boundary rather than 23:59:59 to avoid losing calls at fractional seconds. example: '2026-10-08T00:00:00Z' - name: listId in: query required: false schema: type: integer minimum: 1 maximum: 2147483647 description: >- Optional visible calling-list ID. Filters by each call’s original session attribution, not the contact’s current list membership. Use a positive integer no greater than 2,147,483,647. example: 456 - name: ownerId in: query required: false schema: type: string description: >- Optional PowerDialer user ID for a current workspace member permitted by this key. Omit to include all owners allowed by the credential. example: user_example responses: '200': description: >- A page of visible calls within the requested interval, with evidence limited by granted scopes. headers: X-Request-Id: schema: type: string format: uuid RateLimit-Limit: schema: type: integer RateLimit-Remaining: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/CallPage' example: data: - id: 789 callSid: call_example_789 ownerId: user_example createdAt: '2026-10-07T12:00:00.000Z' updatedAt: '2026-10-07T12:00:00.000Z' contactId: 123 contactName: Alex Morgan phoneNumber: '+12125550100' fromPhoneNumber: '+12125550101' direction: outbound callStatus: Conversation disposition: type: Interested notes: Requested a follow-up. listId: 456 talkTimeSeconds: 150 recording: state: restricted transcript: state: restricted nextCursor: null default: description: >- Error. 400 invalid request; 401 invalid credential; 403 insufficient access; 404 not found; 409 state/idempotency conflict; 413 size limit; 422 verification failure; 429 rate limit (Retry-After seconds); 503 temporary service failure. headers: Retry-After: schema: type: integer X-Request-Id: schema: type: string format: uuid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key message: API key is invalid, expired or revoked requestId: 00000000-0000-4000-8000-000000000004 x-codeSamples: - lang: bash label: cURL source: >- # Replace example resource IDs and ownerId with values from your workspace. : "${POWERDIALER_API_KEY:?Set POWERDIALER_API_KEY to your scoped API key}" curl --request GET \ --url 'https://api.migration.powerdialer.ai/api/public/v2/calls?limit=50&from=2026-10-01T00%3A00%3A00Z&to=2026-10-08T00%3A00%3A00Z' \ --header "Authorization: Bearer $POWERDIALER_API_KEY" components: schemas: CallPage: type: object properties: data: type: array items: $ref: '#/components/schemas/Call' description: Resources in ascending numeric ID order. nextCursor: anyOf: - type: string - type: 'null' description: >- Send this value as after to read the next page. Null means this result has no next page. required: - data - nextCursor examples: - data: - id: 789 callSid: call_example_789 ownerId: user_example createdAt: '2026-10-07T12:00:00.000Z' updatedAt: '2026-10-07T12:00:00.000Z' contactId: 123 contactName: Alex Morgan phoneNumber: '+12125550100' fromPhoneNumber: '+12125550101' direction: outbound callStatus: Conversation disposition: type: Interested notes: Requested a follow-up. listId: 456 talkTimeSeconds: 150 recording: state: restricted transcript: state: restricted nextCursor: null Error: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code. message: type: string description: Human-readable explanation. requestId: type: string format: uuid description: Request identifier to include when investigating a failure. details: type: array items: type: object properties: path: type: string message: type: string required: - path - message description: Validation errors, when available. required: - code - message - requestId required: - error examples: - error: code: insufficient_scope message: Requires contacts:read requestId: 00000000-0000-4000-8000-000000000004 Call: type: object properties: id: type: integer description: >- Internal numeric row ID used for pagination. Use callSid, not this field, in GET /calls/{id}. callSid: type: string description: Call identifier used in GET /calls/{id} and call events. ownerId: type: string description: PowerDialer member attributed to the call. createdAt: type: string format: date-time description: Call record creation time in UTC. Used by the from/to filter. updatedAt: type: string format: date-time description: Last API-visible update time in UTC. contactId: anyOf: - type: integer - type: 'null' description: Related contact ID, or null. contactName: anyOf: - type: string - type: 'null' description: Contact name recorded for the call, or null. phoneNumber: type: string description: Destination phone number recorded for the call. fromPhoneNumber: type: string description: Originating phone number recorded for the call. direction: anyOf: - type: string - type: 'null' description: Stored call direction, or null when absent. callStatus: type: string description: >- Stored call outcome or status. Do not treat this field alone as a verified sales conversion. disposition: anyOf: - type: object properties: type: type: string notes: type: string required: - type - notes - type: 'null' description: Recorded disposition type and notes, or null. listId: anyOf: - type: integer - type: 'null' description: Calling-list ID from the call session, or null. talkTimeSeconds: type: number description: >- Talk duration in seconds, using provider duration when present and recorded call duration otherwise. May be fractional. recording: $ref: '#/components/schemas/Recording' description: >- Recording availability. Requires recordings:read in addition to calls:read. transcript: $ref: '#/components/schemas/Transcript' description: >- Transcript availability and speaker/text segments. Requires transcripts:read in addition to calls:read. required: - id - callSid - ownerId - createdAt - updatedAt - contactId - contactName - phoneNumber - fromPhoneNumber - direction - callStatus - disposition - listId - talkTimeSeconds - recording - transcript examples: - id: 789 callSid: call_example_789 ownerId: user_example createdAt: '2026-10-07T12:00:00.000Z' updatedAt: '2026-10-07T12:00:00.000Z' contactId: 123 contactName: Alex Morgan phoneNumber: '+12125550100' fromPhoneNumber: '+12125550101' direction: outbound callStatus: Conversation disposition: type: Interested notes: Requested a follow-up. listId: 456 talkTimeSeconds: 150 recording: state: restricted transcript: state: restricted Recording: oneOf: - type: object properties: state: type: string enum: - restricted required: - state - type: object properties: state: type: string enum: - available - unavailable url: anyOf: - type: string - type: 'null' required: - state - url description: >- Without recordings:read, only state=restricted is returned. With that permission, available/unavailable indicates stored recording evidence; url can still be null when no usable URL can be resolved. examples: - state: available url: https://recordings.example.com/example-call.mp3 Transcript: oneOf: - type: object properties: state: type: string enum: - restricted required: - state - type: object properties: state: type: string enum: - available - unavailable segments: type: array items: type: object properties: speaker: type: string text: type: string required: - speaker - text required: - state - segments description: >- Without transcripts:read, only state=restricted is returned. With that permission, available means parsed segments exist; unavailable returns an empty segments array. examples: - state: available segments: - speaker: agent text: Is this a good time to talk? - speaker: customer text: Yes, I have a few minutes. securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: pd__. description: >- Issued in Developers. Workspace/owner/scopes come from credential, never acting-user headers. API keys cannot manage API credentials. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.