> ## Documentation Index > Fetch the complete documentation index at: https://docs.skipcall.app/llms.txt > Use this file to discover all available pages before exploring further. # List calls > Returns a paginated list of calls scoped to the workspaces accessible by the API key. Use the `workspaceIds` query parameter to narrow results to a subset of those workspaces. ## OpenAPI ````yaml https://api-public.skipcall.app/docs-json get /v1/calls openapi: 3.0.0 info: title: Skipcall Public API description: >- ## Overview The Skipcall Public API allows you to integrate Skipcall with your applications, CRM, or automation tools. ## Plan Requirements API access is available for **STARTER**, **INTERMÉDIAIRE** and **EXPERT** plans. ## Authentication All API requests require authentication using an API Key. Include your API key in the `Authorization` header: ``` Authorization: Bearer sk_live_your_api_key_here ``` You can generate API keys from your Skipcall dashboard under Settings > API Keys. ## Rate Limiting Rate limits vary by subscription plan: | Plan | Rate Limit | |------|------------| | STARTER | 100 requests/minute | | INTERMÉDIAIRE | 100 requests/minute | | EXPERT | 1000 requests/minute | Rate limit headers are included in every response: - `X-RateLimit-Limit`: Maximum requests per minute for your plan - `X-RateLimit-Remaining`: Remaining requests in the current window - `X-RateLimit-Reset`: Unix timestamp when the rate limit resets ## Errors The API uses standard HTTP status codes: - `200` - Success - `400` - Bad Request (invalid parameters) - `401` - Unauthorized (invalid or missing API key) - `403` - Forbidden (subscription required or plan not eligible) - `404` - Not Found - `429` - Too Many Requests (rate limit exceeded) - `500` - Internal Server Error ### Subscription Errors | Code | Description | |------|-------------| | `SUBSCRIPTION_REQUIRED` | An active subscription is required to access the API | | `PLAN_NOT_ELIGIBLE` | API access requires STARTER, INTERMÉDIAIRE or EXPERT plan | version: '1.0' contact: {} servers: - url: https://api-public.skipcall.app description: Production security: [] tags: - name: Contacts description: Manage your contacts - name: Calls description: Access call history and recordings paths: /v1/calls: get: tags: - Calls summary: List calls description: >- Returns a paginated list of calls scoped to the workspaces accessible by the API key. Use the `workspaceIds` query parameter to narrow results to a subset of those workspaces. operationId: CallController_list parameters: - name: page required: false in: query description: Page number (starts at 1) schema: default: 1 example: 1 type: number - name: limit required: false in: query description: Number of items per page schema: default: 10 example: 10 type: number - name: sort required: false in: query schema: $ref: '#/components/schemas/BaseListSortDTO' - name: filters required: false in: query description: Filters as JSON string schema: type: string - name: workspaceIds required: false in: query description: >- Workspace IDs to narrow down results. Must be a subset of the workspaces accessible by the API key. Omit to return data from every workspace in scope. Accepts either a comma-separated string (`?workspaceIds=uuid1,uuid2`) — the documented format — or repeated array params (`?workspaceIds[]=uuid1&workspaceIds[]=uuid2`). schema: example: >- 550e8400-e29b-41d4-a716-446655440000,6ba7b810-9dad-11d1-80b4-00c04fd430c8 type: string responses: '200': description: Paginated list of calls content: application/json: schema: $ref: '#/components/schemas/PaginatedCallDTO' '401': description: Invalid or missing API key content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: UNAUTHORIZED message: type: string example: Invalid or revoked API key status: type: number example: 401 '403': description: One or more requested workspaceIds are outside the API key scope security: - ApiKey: [] components: schemas: BaseListSortDTO: type: object properties: orderBy: type: string example: createdAt order: type: string enum: - asc - desc default: asc example: asc required: - orderBy - order PaginatedCallDTO: type: object properties: data: type: array items: $ref: '#/components/schemas/CallWithContactDTO' total: type: number example: 100 page: type: number example: 1 limit: type: number example: 10 totalPages: type: number example: 10 required: - data - total - page - limit - totalPages CallWithContactDTO: type: object properties: id: type: string example: 123e4567-e89b-12d3-a456-426614174000 description: Unique identifier of the call history entry callType: type: string example: CALL_SESSION description: Type of the call history entry (e.g., CALL_SESSION, DIRECT_CALL) enum: - CALL_SESSION - DIRECT_CALL phoneNumberId: type: string example: 123e4567-e89b-12d3-a456-426614174002 description: Unique identifier of the phone number used for the call userProviderSid: type: string example: CA123456789 description: Provider SID for the user side of the call adminProviderSid: type: object example: CA987654321 description: Provider SID for the admin side of the call nullable: true providerConferenceId: type: string example: CF123456789 description: Provider conference ID status: type: string example: completed description: Status of the call type: type: string example: outbound description: Type of call (e.g., outbound, inbound) transferred: type: boolean example: false description: Indicates if the call was transferred startedAt: type: object example: '2024-03-20T09:00:00.000Z' description: Start time of the call nullable: true endedAt: type: object example: '2024-03-20T09:15:00.000Z' description: End time of the call nullable: true createdAt: format: date-time type: string example: '2024-03-20T08:55:00.000Z' description: Date and time when the call history entry was created updatedAt: format: date-time type: string example: '2024-03-20T09:16:00.000Z' description: Date and time when the call history entry was last updated sequenceRunId: type: string example: 123e4567-e89b-12d3-a456-426614174003 description: Unique identifier of the related sequence run sequenceId: type: string example: 123e4567-e89b-12d3-a456-426614174010 description: Unique identifier of the parent sequence syncedWithCrmDate: type: object example: '2024-03-20T09:15:00.000Z' description: Date and time when the call was synced with CRM nullable: true deletedAt: format: date-time type: string example: '2024-03-20T09:15:00.000Z' description: Date and time when the call history entry was deleted nullable: true organizationId: type: string example: 123e4567-e89b-12d3-a456-426614174004 description: Unique identifier of the organization organizationMembershipId: type: string example: 123e4567-e89b-12d3-a456-426614174005 description: Unique identifier of the organization membership managedPhoneNumberId: type: string example: 123e4567-e89b-12d3-a456-426614174006 description: Unique identifier of the managed phone number notes: type: string example: Call notes here description: Notes associated with the call contact: description: Contact information associated with the call nullable: true allOf: - $ref: '#/components/schemas/CallContactSummaryDTO' phoneNumber: description: Phone number information associated with the call nullable: true allOf: - $ref: '#/components/schemas/CallPhoneNumberSummaryDTO' caller: description: Caller information (organization member who made the call) nullable: true allOf: - $ref: '#/components/schemas/CallCallerSummaryDTO' callerPhoneNumber: description: Managed phone number used by the caller nullable: true allOf: - $ref: '#/components/schemas/CallPhoneNumberSummaryDTO' required: - id - callType - status - type - startedAt - endedAt - createdAt - contact - phoneNumber - caller - callerPhoneNumber CallContactSummaryDTO: type: object properties: id: type: string example: 123e4567-e89b-12d3-a456-426614174000 description: Unique identifier of the contact firstName: type: string example: John description: First name of the contact lastName: type: string example: Doe description: Last name of the contact isUnknown: type: boolean example: false description: Whether this is an unknown contact (not in the system) required: - id - firstName - lastName - isUnknown CallPhoneNumberSummaryDTO: type: object properties: value: type: string example: '+33612345678' description: The phone number value required: - value CallCallerSummaryDTO: type: object properties: firstName: type: string example: Alice description: First name of the caller lastName: type: string example: Martin description: Last name of the caller required: - firstName - lastName securitySchemes: ApiKey: scheme: bearer bearerFormat: API Key type: http description: Enter your API Key (sk_live_xxx or sk_test_xxx) ````