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

# Count links

> Count workspace links using the same filters as the list endpoint.

Return the number of links that match a set of filters without downloading the
link resources. This is useful for dashboards, import previews, and deciding
how many [List links](/docs/api-reference/links/list) pages you need to request.

## Authentication and permission

This endpoint only requires **Links: Read** (`links.view`):

```http theme={null}
Authorization: Bearer biqli_your_workspace_api_key
Accept: application/json
```

The API key determines the workspace, so do not send a workspace ID. The count
also follows the key owner's current workspace role and therefore always covers
the same visible links as the List endpoint.

## Count every visible link

```bash theme={null}
curl --request GET \
  --url 'https://biq.li/api/v1/link/count' \
  --header 'Authorization: Bearer biqli_your_workspace_api_key' \
  --header 'Accept: application/json'
```

```json theme={null}
{
  "count": 1842,
  "status": "success"
}
```

A count of zero is a successful `200 OK` response.

## Filter the count

Count supports every non-pagination List filter. Combined filters use AND;
multiple `tag_ids` match a link that has any supplied tag.

| Query parameter | Type                | Behavior                                                                             |
| --------------- | ------------------- | ------------------------------------------------------------------------------------ |
| `search`        | string              | Partial search across public link ID, external ID, name, alias, and destination URL. |
| `domain_id`     | string              | Public `biq_dom_...` ID, or `default`.                                               |
| `folder_id`     | string              | Public `biq_fld_...` folder ID.                                                      |
| `tag_ids`       | string or string\[] | Comma-separated or repeated public tag IDs; maximum 100.                             |
| `external_id`   | string              | Exact workspace-unique external ID.                                                  |
| `active`        | boolean             | `true` or `false`.                                                                   |
| `safety_status` | string              | `clear`, `pending`, or `quarantined`.                                                |

`page_size`, `starting_after`, and `ending_before` are intentionally not
accepted because counting is not paginated. Unknown query parameters return
`422 validation_error`.

```bash theme={null}
curl --get 'https://biq.li/api/v1/link/count' \
  --header 'Authorization: Bearer biqli_your_workspace_api_key' \
  --header 'Accept: application/json' \
  --data-urlencode 'active=true' \
  --data-urlencode 'domain_id=default' \
  --data-urlencode 'tag_ids=biq_tag_01M14CC1TW7AQ6DWZG9TMRH0PQ,biq_tag_01M14CD3CA47DTEGTZX90B61QB'
```

Use the identical filters with `GET /v1/link` to retrieve those links.

## Errors

| HTTP status | Error code              | Meaning                                                       |
| ----------- | ----------------------- | ------------------------------------------------------------- |
| `401`       | `invalid_token`         | The workspace API key is missing, invalid, or revoked.        |
| `403`       | `insufficient_scope`    | The key lacks `links.view` or its user lost workspace access. |
| `422`       | `validation_error`      | A filter is unknown, malformed, or out of range.              |
| `429`       | `rate_limit_exceeded`   | The workspace exceeded its API request limit.                 |
| `500`       | `internal_server_error` | An unexpected server error occurred.                          |

Validation errors identify fields under `error.details.errors`. Every error
includes a `request_id` for support and request tracing.

## Shared API behavior

Authentication is workspace-scoped; see [Authentication](/docs/api-reference/authentication). Errors use the standard envelope and request IDs described in [Errors](/docs/api-reference/errors), and requests are subject to [Rate limits](/docs/api-reference/rate-limits).


## OpenAPI

````yaml GET /v1/link/count
openapi: 3.1.0
info:
  title: Biqli API
  version: 1.0.0
  description: Workspace-scoped REST API for Biqli.
servers:
  - url: https://biq.li/api
security:
  - bearerAuth: []
paths:
  /v1/link/count:
    get:
      tags:
        - Links
      summary: Count links
      description: >-
        Counts visible workspace links using the same non-pagination filters as
        List links. Requires links.view.
      operationId: link.count
      parameters:
        - name: search
          in: query
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: domain_id
          in: query
          schema:
            type: string
            pattern: ^(default|biq_dom_[0-9A-HJKMNP-TV-Z]{26})$
        - name: folder_id
          in: query
          schema:
            type: string
            pattern: ^biq_fld_[0-9A-HJKMNP-TV-Z]{26}$
        - name: tag_ids
          in: query
          style: form
          explode: false
          schema:
            type: array
            minItems: 1
            maxItems: 100
            uniqueItems: true
            items:
              type: string
              pattern: ^biq_tag_[0-9A-HJKMNP-TV-Z]{26}$
        - name: external_id
          in: query
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: active
          in: query
          schema:
            type: boolean
        - name: safety_status
          in: query
          schema:
            type: string
            enum:
              - clear
              - pending
              - quarantined
      responses:
        '200':
          description: Count returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountLinksResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CountLinksResponse:
      type: object
      additionalProperties: false
      required:
        - count
        - status
      properties:
        count:
          type: integer
          minimum: 0
        status:
          type: string
          const: success
    ApiError:
      type: object
      required:
        - error
        - request_id
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - invalid_token
                - insufficient_scope
                - upgrade_required
                - quota_exceeded
                - resource_not_found
                - domain_taken
                - alias_taken
                - external_id_taken
                - folder_name_taken
                - tag_name_taken
                - pixel_name_taken
                - biolink_name_taken
                - method_not_allowed
                - url_blocked
                - dns_verification_failed
                - validation_error
                - rate_limit_exceeded
                - internal_server_error
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        request_id:
          type: string
          description: Request identifier to include when contacting support.
  responses:
    Unauthorized:
      $ref: '#/components/responses/ApiErrorResponse'
      description: The workspace API key is missing, invalid, or revoked.
    Forbidden:
      $ref: '#/components/responses/ApiErrorResponse'
      description: >-
        The key lacks a required scope, the workspace must upgrade, or its quota
        is exhausted.
    UnprocessableEntity:
      $ref: '#/components/responses/ApiErrorResponse'
      description: >-
        The payload is invalid, a destination was blocked, or domain DNS
        verification is not ready.
    RateLimited:
      description: The workspace exceeded its plan's API rate limit.
      headers:
        RateLimit-Policy:
          description: Current IETF HTTPAPI quota policy as a structured field.
          schema:
            type: string
            example: '"workspace-api";q=1000;w=60'
        RateLimit:
          description: Current IETF HTTPAPI service limit as a structured field.
          schema:
            type: string
            example: '"workspace-api";r=0;t=17'
        Retry-After:
          description: Seconds to wait before retrying the request.
          schema:
            type: integer
            minimum: 0
            example: 17
        X-RateLimit-Limit:
          description: Legacy maximum request count for the current window.
          schema:
            type: integer
            minimum: 1
            example: 1000
        X-RateLimit-Remaining:
          description: Legacy remaining request count.
          schema:
            type: integer
            minimum: 0
            example: 0
        X-RateLimit-Reset:
          description: Legacy reset time as a UTC Unix timestamp.
          schema:
            type: integer
            format: int64
            example: 1788126519
        X-Biq-Request-Id:
          description: Request identifier for support and tracing.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    InternalError:
      $ref: '#/components/responses/ApiErrorResponse'
      description: The request failed unexpectedly.
    ApiErrorResponse:
      description: API error.
      headers:
        X-Biq-Request-Id:
          description: Request identifier for support and tracing.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Workspace API key
      description: A workspace API key beginning with biqli_.

````