> ## 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 Click Evidence

> Retrieve recorded SMS click requests for one recipient and sending list.

Returns individual short-link click requests recorded for one recipient and one sending list owned by the API-key account. Results are newest first.

<Warning>
  A row proves that Trackly recorded an HTTP request from the returned IP address. It does not prove who operated the device, that the request was human, or that the recipient consented. Link-preview and security scanners can generate requests. A non-null `click_id` was generated only for requests classified as non-bot; a null value can also indicate legacy data.
</Warning>

## Query Parameters

<ParamField query="phone_number" type="string" required>
  Recipient phone number in E.164 format.
</ParamField>

<ParamField query="sending_list_id" type="integer">
  Sending list ID. Either this field or `list_number` is required. When both are supplied, `sending_list_id` takes precedence.
</ParamField>

<ParamField query="list_number" type="string">
  Sending list phone number in E.164 format. Required when `sending_list_id` is omitted.
</ParamField>

<ParamField query="start_date" type="string" required>
  Inclusive UTC start date in `YYYY-MM-DD` format.
</ParamField>

<ParamField query="end_date" type="string" required>
  Inclusive UTC end date in `YYYY-MM-DD` format. The inclusive range cannot exceed 30 calendar days.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque pagination cursor from a previous response's `next_cursor`.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Page size, max 200.
</ParamField>

## Response Fields

<ResponseField name="clicks" type="array">
  Individual recorded click requests.

  <Expandable title="click row">
    <ResponseField name="click_id" type="string">Attribution click ID, or `null` for bot/preview or legacy events.</ResponseField>
    <ResponseField name="ip_address" type="string">IP address recorded for the request, or `null` when unavailable.</ResponseField>
    <ResponseField name="timestamp" type="string">Click time in ISO-8601 UTC.</ResponseField>
    <ResponseField name="message_id" type="string">ID of the message containing the clicked link.</ResponseField>
    <ResponseField name="message_body" type="string">Authoritative recorded sent body, or `null` when unavailable.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  `limit`, `has_more` (boolean), and `next_cursor` (opaque, `null` on the last page).
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -G https://api.tracklysms.com/api/v2/clicks \
    -H "X-Api-Key: trk_your_api_key" \
    --data-urlencode "phone_number=+14155551234" \
    --data-urlencode "list_number=+18005551234" \
    --data-urlencode "start_date=2026-07-01" \
    --data-urlencode "end_date=2026-07-30"
  ```
</RequestExample>

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "clicks": [
      {
        "click_id": "a4f902ef1c80452caea3da16c72c4210",
        "ip_address": "203.0.113.10",
        "timestamp": "2026-07-15T12:00:00Z",
        "message_id": "a1b2c3d4",
        "message_body": "Please confirm your subscription"
      }
    ],
    "pagination": {
      "limit": 50,
      "has_more": false,
      "next_cursor": null
    }
  }
  ```
</ResponseExample>

An unknown or unowned sending list returns an empty `clicks` page rather than revealing whether another account owns it.

Requests are limited to 60 per minute per API key unless that key has a custom rate-limit override.

## Error Codes

| HTTP Status | Error Code             | Description                                                                               |
| ----------- | ---------------------- | ----------------------------------------------------------------------------------------- |
| 400         | `missing_param`        | A required phone, list, or date parameter is missing.                                     |
| 400         | `invalid_param`        | A phone, list ID, date, limit, or cursor is malformed.                                    |
| 400         | `date_range_too_large` | The inclusive date range exceeds 30 calendar days.                                        |
| 429         | `rate_limit_exceeded`  | The API key exceeded its request limit; retry after the response's `Retry-After` seconds. |
| 500         | `query_failed`         | The query could not be executed; retry the request.                                       |

Also `401 invalid_credentials` and `403 account_suspended`.