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

# List All Sending Lists

> Retrieve all sending lists associated with your account.

Returns all sending lists for your account, optionally filtered by status. By default, deleted lists are excluded from results.

## Query Parameters

<ParamField query="status" type="string" optional>
  Filter lists by status. Accepted values: `active`, `paused`, `suspended`, `deleted`. When omitted, all lists except those with `deleted` status are returned.
</ParamField>

## Response Fields

<ResponseField name="lists" type="array">
  Array of sending list objects.

  <Expandable title="List object properties">
    <ResponseField name="id" type="integer">
      Unique identifier for the sending list.
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The phone number associated with the list in E.164 format (e.g. `+12025551234`).
    </ResponseField>

    <ResponseField name="brand_name" type="string">
      The brand name registered for this sending list.
    </ResponseField>

    <ResponseField name="list_name" type="string">
      The display name of the sending list.
    </ResponseField>

    <ResponseField name="list_type" type="string">
      The SMS provider used for this list. One of: `lime`, `infobip`, `twilio`, `cm`, `aloware`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the list. One of: `active`, `paused`, `suspended`, `deleted`.
    </ResponseField>

    <ResponseField name="contact_count" type="integer">
      The number of active contacts on this list. Calculated via aggregation of active ListContacts.
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      ISO 8601 timestamp of when the list was created.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X GET "https://api.tracklysms.com/api/v2/lists?status=active" \
      -H "X-Api-Key: trk_your_api_key_here"
    ```

    ```python Python theme={null}
    import requests

    response = requests.get(
        "https://api.tracklysms.com/api/v2/lists",
        params={"status": "active"},
        headers={"X-Api-Key": "trk_your_api_key_here"}
    )

    data = response.json()
    for lst in data["lists"]:
        print(f"{lst['list_name']} — {lst['contact_count']} contacts")
    ```

    ```javascript Node.js theme={null}
    const response = await fetch(
      "https://api.tracklysms.com/api/v2/lists?status=active",
      {
        headers: {
          "X-Api-Key": "trk_your_api_key_here",
        },
      }
    );

    const data = await response.json();
    console.log(data.lists);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 — Success theme={null}
  {
    "lists": [
      {
        "id": 42,
        "phone_number": "+12025551234",
        "brand_name": "Acme Co",
        "list_name": "Acme Promo List",
        "list_type": "twilio",
        "status": "active",
        "contact_count": 15230,
        "created_at": "2025-03-15T14:30:00"
      },
      {
        "id": 43,
        "phone_number": "+12025559876",
        "brand_name": "Acme Co",
        "list_name": "Acme Welcome List",
        "list_type": "twilio",
        "status": "active",
        "contact_count": 8412,
        "created_at": "2025-04-01T09:00:00"
      }
    ]
  }
  ```

  ```json 401 — Unauthorized theme={null}
  {
    "error": "Invalid credentials",
    "code": "invalid_credentials"
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code            | Description                                                                |
| ----------- | --------------------- | -------------------------------------------------------------------------- |
| 401         | `invalid_credentials` | API key is missing or invalid.                                             |
| 403         | `account_suspended`   | Your account is suspended. Resolve outstanding billing or contact support. |
| 429         | `rate_limited`        | Request throttled; retry with exponential backoff after the window resets. |

## Next Steps

<CardGroup cols={2}>
  <Card title="Contacts Overview" icon="users" href="/guides/contacts/overview">
    Manage contacts across your lists
  </Card>

  <Card title="List Contacts" icon="address-book" href="/api-reference/v2/contacts/list-contacts">
    View contacts on a specific list
  </Card>
</CardGroup>