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

# List Subscriptions

> Retrieve a paginated list of subscriptions with optional filtering and sorting

Retrieves a paginated list of all subscriptions. You can filter and sort the results using query parameters.

## Query Parameters

<ParamField query="page" type="integer" default="1">
  The page number to retrieve (1-indexed).
</ParamField>

<ParamField query="limit" type="integer" default="10">
  The number of subscriptions to return per page. Must be one of: `5`, `10`, `25`, `50`, or `100`. Values exceeding `100` are capped automatically.
</ParamField>

<ParamField query="filters" type="string">
  A JSON-encoded array of filter objects. Each filter object has the following properties:

  <Expandable title="Filter Object">
    <ParamField body="field" type="string" required>
      The field to filter on. Supported fields:

      | Field        | Description                                                             |
      | ------------ | ----------------------------------------------------------------------- |
      | `status`     | Subscription status (`draft`, `sent`, `accepted`, `active`, `canceled`) |
      | `account_id` | The account/customer ID                                                 |
      | `metadata`   | Metadata key-value pairs (use dot notation, e.g. `metadata.custom_key`) |
      | `tag_ids`    | Tag IDs associated with the subscription                                |
      | `owner_id`   | The owner/assignee user ID                                              |
    </ParamField>

    <ParamField body="operator" type="string" required>
      The comparison operator. Supported operators:

      | Operator | Description                                 | Example                      |
      | -------- | ------------------------------------------- | ---------------------------- |
      | `eq`     | Exact match                                 | `"value": "active"`          |
      | `in`     | Matches any value in a comma-separated list | `"value": "active,canceled"` |
    </ParamField>

    <ParamField body="value" type="string" required>
      The value to match against. For the `in` operator, use comma-separated values.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField query="sort" type="string">
  Sort specification in `field:order` format. Order is either `asc` (ascending) or `desc` (descending).

  Sortable fields: `name`, `account_name`, `status`, `activated_at`, `ended_at`, `updated_at`, `contract_start_date`, `contract_end_date`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.alguna.io/subscriptions?page=1&limit=25" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (with filters and sort) theme={null}
  curl -G "https://api.alguna.io/subscriptions" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    --data-urlencode 'page=1' \
    --data-urlencode 'limit=10' \
    --data-urlencode 'filters=[{"field":"status","operator":"in","value":"active,canceled"}]' \
    --data-urlencode 'sort=updated_at:desc'
  ```

  ```javascript Node.js theme={null}
  const subscriptions = await alguna.subscriptions.list({
    page: 1,
    limit: 25,
    filters: [
      { field: "status", operator: "in", value: "active,canceled" },
      { field: "account_id", operator: "eq", value: "acc_abc123" }
    ],
    sort: "updated_at:desc"
  });
  ```
</RequestExample>

## Response

<Snippet file="subscriptions-list-response.mdx" />

<ResponseField name="items" type="array">
  List of subscription objects.

  <Expandable title="Subscription Object">
    <Snippet file="subscription-response-fields.mdx" />
  </Expandable>
</ResponseField>

<ResponseField name="pageCount" type="integer">
  Total number of pages available based on the current limit.
</ResponseField>

<ResponseField name="limit" type="integer">
  The number of items per page used for this request.
</ResponseField>