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

# List Shortlinks

> API to retrieve a paginated list of shortlinks with filtering and sorting options, including associated tags. Supports both session-based auth and API key auth.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/shortlinks/get_shortlinks
openapi: 3.1.0
info:
  title: Dashlink API
  version: 1.0.0
  description: >
    The Dashlink API lets you do programmatically what your team does in the
    Dashlink

    dashboard: create and manage Shortlinks, generate QR codes, organise work
    into

    campaigns, connect your own domains, and read click analytics.


    **Base URL:** `https://api.dashlink.ai`


    **Authentication:** every request needs an API key in the `X-API-Key`
    header.

    Create one in the dashboard under Settings → API Keys.


    ```bash

    curl https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks \
      -H "X-API-Key: dlk_live_..."
    ```


    **Responses** are always wrapped. Success returns `{"data": ...}` and
    failure

    returns `{"error": {"message": ..., "status_code": ..., "code": ...}}`, so
    one

    code path handles every endpoint.


    **Rate limits** depend on your plan, from 500 requests per minute on Free to

    uncapped on Enterprise. Every response carries `X-RateLimit-Remaining`.
  contact:
    name: Dashlink Support
    email: support@dashlink.ai
  license:
    name: Proprietary
    url: https://dashlink.ai/terms
servers:
  - url: https://api.dashlink.ai
    description: Production
security:
  - apiKey: []
tags:
  - name: Links
    description: >-
      Create, read, update and delete Shortlinks. Deletion is bulk-only: to
      delete a single link, pass a one-element array.
  - name: App Dynamic Links
    description: >-
      Links that route to an iOS or Android app when it is installed and fall
      back to the web when it is not. App dynamic links are Shortlink records,
      so an API key granted the `shortlinks` module covers them.
  - name: QR Codes
    description: >-
      Generate and style QR codes. Every QR code is backed by a Shortlink, so
      scans are tracked the same way clicks are.
  - name: Campaigns
    description: >-
      Group links into campaigns and channels so their performance can be
      compared as a unit.
  - name: Analytics
    description: >-
      Click and scan analytics at three scopes: the whole organization, a single
      link, or a campaign. All analytics endpoints are read-only and are subject
      to your plan's retention window.
  - name: Branded Links
    description: >-
      Connect your own domain so Shortlinks carry your brand instead of the
      default Dashlink domain. Covers custom domains you own and platform
      subdomains Dashlink hosts for you.
  - name: Tags
    description: Organise links and QR codes with tags, and filter lists by them.
  - name: UTM Templates
    description: >-
      Reusable sets of UTM parameters, so campaign tagging stays consistent
      across everyone creating links.
  - name: Dynamic Link Templates
    description: >-
      Reusable app setup for Dynamic Links: domain, desktop fallback, and iOS
      and Android behaviour. Applying a template fills the create form. It does
      not change links already created.
  - name: Users & Organization
    description: Read your organization's profile and its members.
  - name: Account Limits
    description: >-
      What your plan allows and how much of it you have used. Check these before
      a bulk create so you fail early rather than halfway through.
paths:
  /api/v1/shortlinks/get_shortlinks:
    get:
      tags:
        - Links
      summary: List Shortlinks
      description: >-
        API to retrieve a paginated list of shortlinks with filtering and
        sorting options, including associated tags. Supports both session-based
        auth and API key auth.
      operationId: shortlinks_get_shortlinks
      parameters:
        - name: page
          in: query
          required: false
          description: 1-based page number. Defaults to 1.
          schema:
            type: string
            default: 1
        - name: per_page
          in: query
          required: false
          description: >-
            Results per page. Defaults to 10, maximum 100. Larger values are
            clamped, not rejected.
          schema:
            type: string
            default: 10
        - name: date_from
          in: query
          required: false
          description: >-
            Start of the window, `YYYY-MM-DD`. Clamped to your plan's retention
            floor.
          schema:
            type: string
        - name: date_to
          in: query
          required: false
          description: End of the window, `YYYY-MM-DD`.
          schema:
            type: string
        - name: custom_backhalf
          in: query
          required: false
          description: >-
            Filter to links that use a custom (chosen) back-half rather than a
            generated one.
          schema:
            type: string
        - name: sort_by
          in: query
          required: false
          description: 'Sort key: `name`, `most_recent` or `last_modified`.'
          schema:
            type: string
            default: last_modified
        - name: order
          in: query
          required: false
          description: 'Sort direction: `asc` or `desc`.'
          schema:
            type: string
            default: desc
        - name: tags
          in: query
          required: false
          description: Tag names to filter by.
          schema:
            type: string
        - name: link_type
          in: query
          required: false
          description: >-
            Kind of link: `shortlink` or `dynamic_link`. Defaults to
            `shortlink`.
          schema:
            type: string
            default: shortlink
        - name: enabled
          in: query
          required: false
          description: Filter by enabled state.
          schema:
            type: string
        - name: password_protected
          in: query
          required: false
          description: Whether the link requires a password.
          schema:
            type: string
        - name: dynamic_routing_enabled
          in: query
          required: false
          description: >-
            Whether `routing_rules` are evaluated for this link. When off, the
            base destination is always served. Defaults to false.
          schema:
            type: string
        - name: link_expiration_enabled
          in: query
          required: false
          description: >-
            Whether the link stops resolving after `expires_at`. Defaults to
            false.
          schema:
            type: string
        - name: is_custom_preview
          in: query
          required: false
          description: >-
            Whether the link uses custom link-preview metadata (`preview_title`,
            `preview_description`, `preview_image`) instead of an auto-generated
            preview. Defaults to false.
          schema:
            type: string
        - name: utm_analytics_enabled
          in: query
          required: false
          description: >-
            Whether UTM parameters are appended to the destination and tracked.
            Defaults to false.
          schema:
            type: string
        - name: qr_code_enabled
          in: query
          required: false
          description: Whether to generate a QR code for this link. Defaults to false.
          schema:
            type: string
        - name: destination_types
          in: query
          required: false
          description: >-
            Filter the list to these destination types, comma-separated (`url`,
            `wifi`, `sms`, `call`, `email`, `vcard`).
          schema:
            type: string
      responses:
        '200':
          description: Success.
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Requests allowed per minute on your plan. `-1` means uncapped.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Requests left in the current window.
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until the window resets.
            X-RateLimit-Plan:
              schema:
                type: string
              description: The plan the limit was derived from.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    allOf:
                      - $ref: '#/components/schemas/Pagination'
                      - type: object
                        description: The endpoint's payload.
                        additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    Pagination:
      type: object
      description: Returned alongside the collection on every list endpoint.
      properties:
        total_count:
          type: integer
          description: Total matching records.
        total_pages:
          type: integer
          description: Total pages at this `per_page`.
        current_page:
          type: integer
          description: The page returned.
        per_page:
          type: integer
          description: Records per page, after clamping to the maximum of 100.
    Error:
      type: object
      description: The single error shape returned by every endpoint.
      properties:
        error:
          type: object
          required:
            - message
            - status_code
          properties:
            message:
              type: string
              description: A human-readable description of what went wrong.
            status_code:
              type: integer
              description: Matches the HTTP status code of the response.
            code:
              type: string
              description: >-
                A stable machine-readable code such as `NOT_FOUND` or
                `RATE_LIMIT_EXCEEDED`. Branch on this rather than on the message
                text.
            details:
              type: object
              description: >-
                Which parameter was at fault, when the error is about a
                parameter.
              additionalProperties: true
  responses:
    BadRequest:
      description: A parameter is missing, malformed, or outside its allowed range.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: >-
                Invalid sort_by option. Choose from name, most_recent,
                last_modified
              status_code: 400
              code: INVALID_PARAMETER
              details:
                parameter: sort_by
                value: most_clicked
                valid_options:
                  - name
                  - most_recent
                  - last_modified
    Unauthorized:
      description: The API key is missing, malformed, expired, or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Authentication required. Please provide valid credentials.
              status_code: 401
              code: AUTHENTICATION_REQUIRED
    Forbidden:
      description: >-
        The key is valid but is not permitted to do this. Usually a restricted
        key without the right module grant, or a read-only key attempting a
        write.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: You do not have permission to perform this action.
              status_code: 403
              code: PERMISSION_DENIED
    NotFound:
      description: >-
        No such resource. Also returned for a resource that belongs to another
        organization, so the response cannot be used to discover which ids
        exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Shortlink not found.
              status_code: 404
              code: NOT_FOUND
    RateLimited:
      description: >-
        Too many requests this minute. `Retry-After` says how many seconds to
        wait; `X-RateLimit-Reset` says when the window rolls over.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Rate limit exceeded. Please retry in 43 seconds.
              status_code: 429
              code: RATE_LIMIT_EXCEEDED
    ServerError:
      description: Something failed on our side. Safe to retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: An unexpected error occurred. Please try again.
              status_code: 500
              code: INTERNAL_SERVER_ERROR
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your API key, for example `dlk_live_...`. Create one in the dashboard
        under Settings → API Keys. Keys are shown once at creation and stored
        only as a hash, so they cannot be recovered.

````

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