> ## 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 calling lists > Find the calling lists available to your integration before assigning contacts or reporting on list performance. Requires `lists:read`. Personal keys see their owner's lists; workspace keys see lists within their configured owner restrictions. Names are display labels and need not be unique, so retain each numeric list ID. Results are ordered by increasing ID and include name, owner, group and contact count. Follow `nextCursor` with `after` until it is null. Pagination is not a snapshot: reconcile concurrent list changes through the change feed when maintaining a local copy. A successful empty page means no currently visible lists. `400 invalid_request` indicates an invalid cursor, page size or unsupported filter; `403 insufficient_scope` means this key cannot read lists. Reads can be retried after transient errors without an idempotency key. See [calling-list management](/guides/contact-lists). ## OpenAPI ````yaml /api/openapi.json get /lists 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: /lists: get: tags: - Calling lists summary: List calling lists description: >- Find the calling lists available to your integration before assigning contacts or reporting on list performance. Requires `lists:read`. Personal keys see their owner's lists; workspace keys see lists within their configured owner restrictions. Names are display labels and need not be unique, so retain each numeric list ID. Results are ordered by increasing ID and include name, owner, group and contact count. Follow `nextCursor` with `after` until it is null. Pagination is not a snapshot: reconcile concurrent list changes through the change feed when maintaining a local copy. A successful empty page means no currently visible lists. `400 invalid_request` indicates an invalid cursor, page size or unsupported filter; `403 insufficient_scope` means this key cannot read lists. Reads can be retried after transient errors without an idempotency key. See [calling-list management](/guides/contact-lists). operationId: getLists 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 responses: '200': description: >- A page of visible calling lists, including each list ID and current contact count. 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/ListPage' example: data: - name: October inbound leads ownerId: user_example groupName: Inbound id: 456 orgId: org_example createdAt: '2026-10-08T12:00:00.000Z' updatedAt: '2026-10-08T12:00:00.000Z' contactsCount: 1 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/lists?limit=50' \ --header "Authorization: Bearer $POWERDIALER_API_KEY" components: schemas: ListPage: type: object properties: data: type: array items: $ref: '#/components/schemas/List' 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: - name: October inbound leads ownerId: user_example groupName: Inbound id: 456 orgId: org_example createdAt: '2026-10-08T12:00:00.000Z' updatedAt: '2026-10-08T12:00:00.000Z' contactsCount: 1 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 List: type: object properties: id: type: integer description: >- PowerDialer list ID. Use this integer in list URLs and analytics filters. name: type: string description: Calling-list display name. ownerId: type: string description: PowerDialer member who owns this list. orgId: anyOf: - type: string - type: 'null' description: Workspace identifier stored on the list. groupName: anyOf: - type: string - type: 'null' description: Optional grouping label, or null. createdAt: type: string format: date-time description: List creation time in UTC. updatedAt: type: string format: date-time description: Last list update time in UTC. contactsCount: type: integer description: >- Stored total membership count for the list. It may exceed the contacts visible to a restricted key. required: - id - name - ownerId - orgId - groupName - createdAt - updatedAt - contactsCount examples: - name: October inbound leads ownerId: user_example groupName: Inbound id: 456 orgId: org_example createdAt: '2026-10-08T12:00:00.000Z' updatedAt: '2026-10-08T12:00:00.000Z' contactsCount: 1 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.