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

> Retrieve all schedules for the authenticated account.

List all schedules associated with your account. Returns all non-archived schedules by default. Use the `status` filter to include archived schedules or narrow results to a specific status.

No pagination is applied — the full list of matching schedules is returned in a single response.

## Query Parameters

<ParamField query="status" type="string" optional>
  Comma-separated list of statuses to filter by. Allowed values: `draft`, `off`, `on`, `complete`, `archive`. When omitted, all schedules except those with status `archive` are returned.
</ParamField>

<ParamField query="send_type" type="string" optional>
  Filter by send type. Allowed values: `blast` or `automated`.
</ParamField>

## Response Fields

<ResponseField name="schedules" type="array">
  An array of schedule objects.

  <Expandable title="Schedule object properties">
    <ResponseField name="id" type="string">
      Unique identifier for the schedule.
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the schedule.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status. One of: `draft`, `off`, `on`, `complete`, `archive`.
    </ResponseField>

    <ResponseField name="send_type" type="string">
      Type of schedule. One of: `blast` or `automated`.
    </ResponseField>

    <ResponseField name="source_lists" type="array of integers">
      IDs of the source sending lists assigned to this schedule.
    </ResponseField>

    <ResponseField name="audiences" type="array of strings">
      IDs of the audiences targeted by this schedule.
    </ResponseField>

    <ResponseField name="is_repeating" type="boolean">
      Whether this schedule repeats on selected days of the week.
    </ResponseField>

    <ResponseField name="send_time" type="string">
      Time of day to send, in `HH:MM` format (24-hour).
    </ResponseField>

    <ResponseField name="send_date" type="datetime">
      The specific date for a one-time (non-repeating) schedule.
    </ResponseField>

    <ResponseField name="start_date" type="datetime">
      Start date for a repeating schedule.
    </ResponseField>

    <ResponseField name="end_date" type="datetime">
      End date for a repeating schedule.
    </ResponseField>

    <ResponseField name="days_of_week" type="object">
      Which days the repeating schedule is active. Contains boolean fields: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
    </ResponseField>

    <ResponseField name="skip_within_hours" type="float">
      Skip sending to a contact if they were already sent to within this many hours.
    </ResponseField>

    <ResponseField name="use_local_time" type="boolean">
      Whether `send_time` is interpreted in each recipient's local timezone.
    </ResponseField>

    <ResponseField name="filter_bots" type="boolean">
      Whether bot filtering is enabled for this schedule.
    </ResponseField>

    <ResponseField name="is_mms" type="boolean">
      Whether this schedule sends MMS messages.
    </ResponseField>

    <ResponseField name="is_cto" type="boolean">
      Whether click-to-open mode is enabled.
    </ResponseField>

    <ResponseField name="automated_percent" type="float">
      Percentage of the audience allocated to automated creative selection.
    </ResponseField>

    <ResponseField name="ir_revenue" type="float">
      Expected or target revenue from this send.
    </ResponseField>

    <ResponseField name="blasts" type="array">
      Array of blast variant objects.

      <Expandable title="Blast object properties">
        <ResponseField name="message" type="string">
          Message body text. May contain `{{link1}}`, `{{link2}}`, etc. placeholders for offer links.
        </ResponseField>

        <ResponseField name="offer_links" type="array">
          Array of offer link objects. Each contains `key` (string, e.g. `link1`), `offer_id` (string, `null` when the link uses a custom URL), `custom_url` (string, `null` when the link uses an offer), and `url_params` (object of key/value query parameters).
        </ResponseField>

        <ResponseField name="percent_audience" type="float">
          Percentage of the audience that receives this variant. All blast percentages must sum to 100.
        </ResponseField>

        <ResponseField name="variant_name" type="string">
          Display name for this variant.
        </ResponseField>

        <ResponseField name="mms_image_url" type="string">
          URL of the MMS image attachment, if applicable.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Timestamp when the schedule was created.
    </ResponseField>

    <ResponseField name="updated_at" type="datetime">
      Timestamp when the schedule was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X GET "https://api.tracklysms.com/api/v2/schedules?status=on,draft&send_type=blast" \
      -H "X-Api-Key: trk_your_api_key_here"
    ```

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

    response = requests.get(
        "https://api.tracklysms.com/api/v2/schedules",
        headers={"X-Api-Key": "trk_your_api_key_here"},
        params={
            "status": "on,draft",
            "send_type": "blast"
        }
    )

    data = response.json()
    for schedule in data["schedules"]:
        print(f"{schedule['name']} — {schedule['status']}")
    ```

    ```javascript Node.js theme={null}
    const response = await fetch(
      "https://api.tracklysms.com/api/v2/schedules?status=on,draft&send_type=blast",
      {
        method: "GET",
        headers: {
          "X-Api-Key": "trk_your_api_key_here"
        }
      }
    );

    const data = await response.json();
    data.schedules.forEach(schedule => {
      console.log(`${schedule.name} — ${schedule.status}`);
    });
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 — Success theme={null}
  {
    "schedules": [
      {
        "id": "6651a3f2e4b0a1c2d3e4f567",
        "name": "Weekend Promo Blast",
        "status": "on",
        "send_type": "blast",
        "source_lists": [101, 204],
        "audiences": ["665fa1b2c3d4e5f6a7b8c901"],
        "is_repeating": true,
        "send_time": "14:30",
        "send_date": null,
        "start_date": "2025-06-01T00:00:00",
        "end_date": "2025-08-31T00:00:00",
        "days_of_week": {
          "monday": false,
          "tuesday": false,
          "wednesday": false,
          "thursday": false,
          "friday": true,
          "saturday": true,
          "sunday": true
        },
        "skip_within_hours": 24,
        "use_local_time": true,
        "filter_bots": true,
        "is_mms": false,
        "is_cto": false,
        "automated_percent": 0,
        "ir_revenue": 2.50,
        "blasts": [
          {
            "message": "Flash sale this weekend! Shop now: {{link1}}",
            "offer_links": [
              {
                "key": "link1",
                "offer_id": "665fa1b2c3d4e5f6a7b8c902",
                "custom_url": null,
                "url_params": {"utm_source": "sms", "utm_campaign": "weekend"}
              }
            ],
            "percent_audience": 60,
            "variant_name": "Control",
            "mms_image_url": null
          },
          {
            "message": "Don't miss out — 20% off everything: {{link1}}",
            "offer_links": [
              {
                "key": "link1",
                "offer_id": "665fa1b2c3d4e5f6a7b8c902",
                "custom_url": null,
                "url_params": {"utm_source": "sms", "utm_campaign": "weekend"}
              }
            ],
            "percent_audience": 40,
            "variant_name": "Urgency Variant",
            "mms_image_url": null
          }
        ],
        "created_at": "2025-05-28T10:15:30",
        "updated_at": "2025-06-01T08:00:00"
      }
    ]
  }
  ```

  ```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, invalid, or revoked.                                   |
| 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="Campaign Scheduling" icon="calendar" href="/guides/campaigns/scheduling">
    Plan and schedule campaigns
  </Card>

  <Card title="List Audiences" icon="users" href="/api-reference/v2/audiences/list-audiences">
    View available audiences
  </Card>
</CardGroup>