> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lobbystack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List calls

> Newest first. Filter by start time to read one day or one week.



## OpenAPI

````yaml /api-reference/openapi.json get /calls
openapi: 3.1.0
info:
  title: LobbyStack API
  version: v1
  description: >-
    Read calls, contacts, appointments and messages, book appointments, and
    subscribe to webhooks. Authenticate with an API key in the Authorization
    header. Each key allows 120 requests per minute by default.
servers:
  - url: https://app.lobbystack.com/api/v1
security:
  - bearerAuth: []
tags:
  - name: Business
  - name: Calls
  - name: Contacts
  - name: Appointments
  - name: Messages
  - name: Knowledge
  - name: Webhooks
paths:
  /calls:
    get:
      tags:
        - Calls
      summary: List calls
      description: Newest first. Filter by start time to read one day or one week.
      operationId: listCalls
      parameters:
        - name: limit
          in: query
          description: Items per page, 1 to 100. Defaults to 25.
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: cursor
          in: query
          description: The next_cursor value from the previous page.
          schema:
            type: string
        - name: started_after
          in: query
          description: Only calls that started at or after this time.
          schema:
            type: string
            format: date-time
        - name: started_before
          in: query
          description: Only calls that started before this time.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - next_cursor
                  - has_more
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Call'
                  next_cursor:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Pass as cursor to get the next page. Null on the last
                      page.
                  has_more:
                    type: boolean
        '400':
          description: The request is invalid (invalid_request).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, invalid, or revoked (unauthorized).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The API key lacks the calls:read scope (insufficient_scope).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Too many requests (rate_limited). Wait for the Retry-After header's
            number of seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait.
      security:
        - bearerAuth: []
components:
  schemas:
    Call:
      type: object
      properties:
        id:
          description: Stable identifier (UUID).
          type: string
          format: uuid
        channel:
          description: >-
            phone: a phone call. web: a browser call from the website or
            dashboard.
          type: string
          enum:
            - phone
            - web
        status:
          type: string
          enum:
            - in_progress
            - completed
        outcome:
          type: string
          enum:
            - appointment_booked
            - booking_incomplete
            - message_taken
            - conversation
            - none
        summary:
          description: Short summary of the call, when one is available.
          anyOf:
            - type: string
            - type: 'null'
        end_reason:
          description: >-
            Why the call ended, as reported by the call provider or
            receptionist.
          anyOf:
            - type: string
            - type: 'null'
        contact_id:
          anyOf:
            - description: Stable identifier (UUID).
              type: string
              format: uuid
            - type: 'null'
        caller_name:
          anyOf:
            - type: string
            - type: 'null'
        caller_phone:
          anyOf:
            - type: string
            - type: 'null'
        duration_seconds:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        recording_available:
          type: boolean
        started_at:
          description: ISO 8601 timestamp in UTC.
          type: string
          format: date-time
        ended_at:
          anyOf:
            - description: ISO 8601 timestamp in UTC.
              type: string
              format: date-time
            - type: 'null'
        created_at:
          description: ISO 8601 timestamp in UTC.
          type: string
          format: date-time
      required:
        - id
        - channel
        - status
        - outcome
        - summary
        - end_reason
        - contact_id
        - caller_name
        - caller_phone
        - duration_seconds
        - recording_available
        - started_at
        - ended_at
        - created_at
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - invalid_request
                - unauthorized
                - forbidden
                - insufficient_scope
                - not_found
                - conflict
                - idempotency_key_reused
                - idempotency_request_in_progress
                - booking_disabled
                - booking_requires_confirmation
                - slot_unavailable
                - rate_limited
                - rate_limit_unavailable
                - method_not_allowed
                - internal_error
            message:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                  message:
                    type: string
                required:
                  - path
                  - message
                additionalProperties: false
          required:
            - code
            - message
          additionalProperties: false
      required:
        - error
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key from Settings > API keys. Scopes: business:read,
        business:write, calls:read, contacts:read, contacts:write,
        appointments:read, appointments:write, messages:read, knowledge:write,
        webhooks:manage.

````