> ## 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 Creatives

> Retrieve a paginated list of all creatives in your account.

Returns all creatives for your account with support for filtering by status and creative type. Results are paginated.

## Query Parameters

<ParamField query="status" type="string" default="active">
  Filter creatives by status. Accepted values: `active`, `paused`, `archived`.
</ParamField>

<ParamField query="creative_type" type="string" optional>
  Filter creatives by type. Accepted values: `automated`, `one_time`, `welcome`. When omitted, all types are returned.
</ParamField>

<ParamField query="page" type="integer" default={1}>
  The page number to return.
</ParamField>

<ParamField query="per_page" type="integer" default={50}>
  Number of creatives per page. Maximum: `100`.
</ParamField>

<ParamField query="list_id" type="integer" optional>
  Filter to creatives whose `list_control_ids` include this list ID.
</ParamField>

## Response Fields

<ResponseField name="creatives" type="array">
  Array of creative objects.

  <Expandable title="Creative object properties">
    <ResponseField name="id" type="integer">
      Unique identifier for the creative.
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name of the creative.
    </ResponseField>

    <ResponseField name="message" type="string">
      The message template. Contains `{{linkN}}` placeholders (e.g. `{{link1}}`, `{{link2}}`) that are replaced with tracked short links at send time.
    </ResponseField>

    <ResponseField name="offer_links" type="array">
      Array of offer link objects that map to placeholders in the message.

      <Expandable title="Offer link properties">
        <ResponseField name="key" type="string">
          The placeholder key (e.g. `link1`). Corresponds to `{{link1}}` in the message.
        </ResponseField>

        <ResponseField name="offer_id" type="string">
          The ID of the offer associated with this link. A 24-character hexadecimal ObjectId.
        </ResponseField>

        <ResponseField name="url" type="string">
          Optional URL override. When set, this URL is used instead of the offer's default URL.
        </ResponseField>

        <ResponseField name="url_params" type="object">
          Optional additional query parameters appended to the link URL.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="offers" type="array">
      Array of offer ID strings referenced by this creative.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status. One of: `active`, `paused`, `archived`.
    </ResponseField>

    <ResponseField name="creative_type" type="string">
      The type of creative. One of: `automated`, `one_time`, `welcome`.
    </ResponseField>

    <ResponseField name="character_count" type="integer">
      Estimated character count of the rendered message. Link placeholders are estimated as 23 characters, and 34 characters of compliance overhead are added.
    </ResponseField>

    <ResponseField name="segment_count" type="integer">
      Estimated number of SMS segments, encoding-aware. The message is expanded (link placeholders as 23 characters plus 34 characters of compliance overhead) and segmented the way carriers bill it. GSM-7 messages fit 160 septets in a single segment, or 153 septets per part when concatenated; extension-table characters (`^ { } [ ] ~ | € \` and form-feed) cost 2 septets each. If the message contains any non-GSM-7 character (e.g. emoji), UCS-2 encoding applies instead: 70 characters single, 67 per concatenated part.
    </ResponseField>

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

    <ResponseField name="slug" type="string">
      Auto-generated unique slug for the creative.
    </ResponseField>

    <ResponseField name="list_control_mode" type="string">
      List targeting control mode. One of: `all` (default), `include`, `exclude`.
    </ResponseField>

    <ResponseField name="list_control_ids" type="array">
      List IDs used when `list_control_mode` is `include` or `exclude`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable title="Pagination properties">
    <ResponseField name="page" type="integer">
      Current page number.
    </ResponseField>

    <ResponseField name="per_page" type="integer">
      Number of items per page.
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of creatives matching the filters.
    </ResponseField>

    <ResponseField name="total_pages" type="integer">
      Total number of pages.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.tracklysms.com/api/v2/creatives?status=active&creative_type=automated&page=1&per_page=25" \
    -H "X-Api-Key: trk_your_api_key_here"
  ```

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

  response = requests.get(
      "https://api.tracklysms.com/api/v2/creatives",
      params={
          "status": "active",
          "creative_type": "automated",
          "page": 1,
          "per_page": 25
      },
      headers={"X-Api-Key": "trk_your_api_key_here"}
  )

  data = response.json()
  for creative in data["creatives"]:
      print(f"{creative['name']} — {creative['segment_count']} segment(s)")

  print(f"Page {data['pagination']['page']} of {data['pagination']['total_pages']}")
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    status: "active",
    creative_type: "automated",
    page: "1",
    per_page: "25",
  });

  const response = await fetch(
    `https://api.tracklysms.com/api/v2/creatives?${params}`,
    {
      headers: {
        "X-Api-Key": "trk_your_api_key_here",
      },
    }
  );

  const data = await response.json();
  console.log(data.creatives);
  console.log(`Page ${data.pagination.page} of ${data.pagination.total_pages}`);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — Success theme={null}
  {
    "creatives": [
      {
        "id": 101,
        "name": "Summer Sale Promo",
        "message": "Hot deals just for you! Shop now: {{link1}} Reply STOP to opt out.",
        "offer_links": [
          {
            "key": "link1",
            "offer_id": "665f1a2b3c4d5e6f70819201",
            "url": null,
            "url_params": {"sub1": "sms"}
          }
        ],
        "offers": ["665f1a2b3c4d5e6f70819201"],
        "status": "active",
        "creative_type": "automated",
        "character_count": 114,
        "segment_count": 1,
        "created_at": "2025-06-10T12:00:00",
        "slug": "cre_summer-sale-promo_a1b2c3",
        "list_control_mode": "all",
        "list_control_ids": []
      },
      {
        "id": 102,
        "name": "New Arrivals Alert",
        "message": "Check out what just dropped: {{link1}} See more: {{link2}} Reply STOP to opt out.",
        "offer_links": [
          {
            "key": "link1",
            "offer_id": "665f1a2b3c4d5e6f70819202",
            "url": null,
            "url_params": {}
          },
          {
            "key": "link2",
            "offer_id": "665f1a2b3c4d5e6f70819203",
            "url": "https://example.com/new",
            "url_params": {}
          }
        ],
        "offers": ["665f1a2b3c4d5e6f70819202", "665f1a2b3c4d5e6f70819203"],
        "status": "active",
        "creative_type": "automated",
        "character_count": 143,
        "segment_count": 1,
        "created_at": "2025-06-12T08:30:00",
        "slug": "cre_new-arrivals-alert_d4e5f6",
        "list_control_mode": "all",
        "list_control_ids": []
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total": 2,
      "total_pages": 1
    }
  }
  ```

  ```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="Creative Templates" icon="paintbrush" href="/guides/creatives/templates">
    Design effective message templates
  </Card>

  <Card title="Create Schedule" icon="calendar" href="/api-reference/v2/schedules/create-schedule">
    Use creatives in a scheduled campaign
  </Card>
</CardGroup>