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

# List the Block list

> Lists the numbers your account never calls, ordered by number. Pass `next_cursor` back as `cursor` for the next page. Requires scope: `leads:read`.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/block-list
openapi: 3.0.3
info:
  title: TopCalls Voice API
  description: |
    Place and manage AI phone calls, campaigns, leads and phone numbers.

    ## Authentication

    Send your API key as a bearer token on every request:

    ```
    Authorization: Bearer tc_live_xxxxx
    ```

    A missing or invalid key gets `401`. Keys carry scopes, and a key without
    the scope an endpoint needs gets `403`.

    ## Rate limits

    The first three limits are per account, so every API key on the account
    shares them. The last is per IP address.

    - All `/v1` endpoints: 120 requests per minute unless we've raised it for
      your account. Over it, you get `429` with `Retry-After` and a plain-text
      body. Responses carry `RateLimit-Limit`, `RateLimit-Remaining` and
      `RateLimit-Reset`.
    - `POST /v1/calls` also counts against your account's
      `max_calls_per_minute` (default 20) in a fixed 60-second window. Going
      over returns `429`, `Retry-After: 60` and `code: RATE_LIMITED`. A request
      counts once its body validates, even if it then fails (say, a `404` on an
      unknown `lead_id`).
    - A call placed while every concurrent-call slot is busy gets `429` with
      `code: concurrency_limit` and no `Retry-After`. Retry once a call ends.
    - Failed authentication: after 600 requests within a minute whose API key
      is refused with `401`, every `/v1` request from that IP address gets
      `429` with `Retry-After` until the minute is up, even one with a valid key.

    On a `429` with `Retry-After`, wait that many seconds, then retry. Back off
    longer on repeats.

    ## Error format

    Errors are RFC 7807 Problem+JSON (`application/problem+json`), except the
    plain-text 120-per-minute `429`. Branch on `status` and `code`:

    ```json
    {
      "status": 402,
      "title": "Insufficient Quota",
      "code": "insufficient_quota",
      "detail": "Not enough credit to place this call. Add credit in Billing (steps: https://docs.topcalls.ai/concepts/credit#adding-credit).",
      "available": 0.5,
      "requested": 2
    }
    ```
  version: 1.0.0
  contact:
    name: TopCalls Support
    url: https://topcalls.ai
  license:
    name: Proprietary
servers:
  - url: https://api.topcalls.ai
    description: Production
security: []
tags:
  - name: Calls
    description: Place and manage phone calls
  - name: Campaigns
    description: Create, run and test call campaigns
  - name: Phone Numbers
    description: Phone numbers and carriers
  - name: Account
    description: Credit balance, credit ledger, call price quotes and daily call analytics
  - name: Webhooks
    description: Webhook subscriptions and events
  - name: Configuration
    description: Available models, voices and platform capabilities
paths:
  /v1/block-list:
    get:
      summary: List the Block list
      description: >-
        Lists the numbers your account never calls, ordered by number. Pass
        `next_cursor` back as `cursor` for the next page. Requires scope:
        `leads:read`.
      parameters:
        - in: query
          name: cursor
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockListPage'
        '400':
          description: Invalid `limit` or `cursor`
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - bearerAuth: []
components:
  schemas:
    BlockListPage:
      type: object
      required:
        - items
        - next_cursor
        - has_more
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BlockListEntry'
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    Problem:
      type: object
      required:
        - status
        - title
      properties:
        type:
          type: string
          format: uri
          description: Error type URI. Not every error sets it.
        title:
          type: string
          description: Short summary of the error.
        status:
          type: integer
          description: HTTP status code.
        detail:
          type: string
          description: What went wrong, in plain words.
        code:
          type: string
          description: >-
            Stable code to branch on, sent on errors that have one (such as
            `insufficient_quota` or `PROMPT_SAFETY_FRAUD`). Each endpoint's
            examples show its values.
        instance:
          type: string
          description: >-
            Request id, sent on some errors. It's your `X-Request-Id` header
            when you sent one.
        errors:
          type: array
          description: Field-level validation failures, on `400`.
          items:
            type: object
            properties:
              path:
                type: string
                description: Field path, such as `phone_number`.
              message:
                type: string
                description: What's wrong with the field.
              code:
                type: string
                description: Validation code, such as `invalid_string` or `custom`.
    BlockListEntry:
      type: object
      required:
        - phone_e164
        - source
        - note
        - call_id
        - created_at
      properties:
        phone_e164:
          type: string
          example: '+14155551234'
        source:
          type: string
          enum:
            - ai_call
            - manual
            - csv
            - api
          description: >-
            `ai_call` when the person asked on a call not to be called again;
            `manual` and `csv` from the dashboard; `api` from this API.
        note:
          type: string
          nullable: true
        call_id:
          type: string
          format: uuid
          nullable: true
          description: The call where the person asked, for `ai_call`.
        created_at:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Use `Authorization: Bearer tc_live_xxxxx`

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.