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

# Update Audience

> Update an existing audience's name, description, source lists, or filter.

Updates the specified audience. All body parameters are optional — only the fields you include will be updated. If the `filter` is changed, the `cached_size` is cleared and must be recalculated using the [Get Audience Size](/api-reference/v2/audiences/get-audience-size) endpoint.

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the audience to update.
</ParamField>

## Body Parameters

<ParamField body="name" type="string">
  Updated audience name. Maximum 255 characters.
</ParamField>

<ParamField body="description" type="string">
  Updated audience description. Maximum 1000 characters. A longer value currently returns a `500` error rather than a validation error.
</ParamField>

<ParamField body="source_lists" type="array of integers">
  Updated sending list IDs to scope the audience. Empty array means all lists.
</ParamField>

<ParamField body="filter" type="object">
  Updated filter group definition. See the [Audience Filter DSL](/api-reference/v2/audience-filter-dsl) reference for the full specification. Changing the filter clears the cached audience size.
</ParamField>

## Response Fields

The response is the full updated audience object (flat, not wrapped).

<ResponseField name="id" type="string">
  Unique audience identifier.
</ResponseField>

<ResponseField name="name" type="string">
  Audience name.
</ResponseField>

<ResponseField name="description" type="string">
  Audience description.
</ResponseField>

<ResponseField name="source_lists" type="array of integers">
  Sending list IDs this audience is scoped to.
</ResponseField>

<ResponseField name="filter" type="object">
  The filter group definition. Condition objects use camelCase keys (e.g. `conditionType`).
</ResponseField>

<ResponseField name="cached_size" type="integer">
  Cached audience size. Reset to `null` if filter was changed.
</ResponseField>

<ResponseField name="cached_size_updated_at" type="datetime">
  Timestamp of last size calculation. Reset to `null` if filter was changed.
</ResponseField>

<ResponseField name="status" type="string">
  Audience status.
</ResponseField>

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

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.tracklysms.com/api/v2/audiences/664f1a2b3c4d5e6f7a8b9c0d" \
    -H "X-Api-Key: trk_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "High-Value Clickers (Updated)",
      "filter": {
        "operator": "AND",
        "conditions": [
          {
            "condition_type": "time",
            "field": "last_clicked_at",
            "operator": "within",
            "value": 14,
            "unit": "days"
          },
          {
            "condition_type": "count",
            "field": "click_count",
            "operator": "gte",
            "value": 5
          }
        ]
      }
    }'
  ```

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

  audience_id = "664f1a2b3c4d5e6f7a8b9c0d"

  response = requests.put(
      f"https://api.tracklysms.com/api/v2/audiences/{audience_id}",
      headers={
          "X-Api-Key": "trk_your_api_key_here",
          "Content-Type": "application/json",
      },
      json={
          "name": "High-Value Clickers (Updated)",
          "filter": {
              "operator": "AND",
              "conditions": [
                  {
                      "condition_type": "time",
                      "field": "last_clicked_at",
                      "operator": "within",
                      "value": 14,
                      "unit": "days",
                  },
                  {
                      "condition_type": "count",
                      "field": "click_count",
                      "operator": "gte",
                      "value": 5,
                  },
              ],
          },
      },
  )

  audience = response.json()
  print(f"Updated: {audience['name']}")
  ```

  ```javascript Node.js theme={null}
  const audienceId = "664f1a2b3c4d5e6f7a8b9c0d";

  const response = await fetch(
    `https://api.tracklysms.com/api/v2/audiences/${audienceId}`,
    {
      method: "PUT",
      headers: {
        "X-Api-Key": "trk_your_api_key_here",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "High-Value Clickers (Updated)",
        filter: {
          operator: "AND",
          conditions: [
            {
              condition_type: "time",
              field: "last_clicked_at",
              operator: "within",
              value: 14,
              unit: "days",
            },
            {
              condition_type: "count",
              field: "click_count",
              operator: "gte",
              value: 5,
            },
          ],
        },
      }),
    }
  );

  const audience = await response.json();
  console.log(`Updated: ${audience.name}`);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — Success theme={null}
  {
    "id": "664f1a2b3c4d5e6f7a8b9c0d",
    "name": "High-Value Clickers (Updated)",
    "description": "Contacts who clicked at least 3 times in the last 30 days",
    "source_lists": [101, 102],
    "filter": {
      "operator": "AND",
      "conditions": [
        {
          "conditionType": "time",
          "field": "last_clicked_at",
          "operator": "within",
          "value": 14,
          "unit": "days",
          "listId": null
        },
        {
          "conditionType": "count",
          "field": "click_count",
          "operator": "gte",
          "value": 5,
          "unit": null,
          "listId": null
        }
      ],
      "groups": []
    },
    "cached_size": null,
    "cached_size_updated_at": null,
    "status": "active",
    "created_at": "2025-10-01T14:22:00"
  }
  ```

  ```json 400 — Invalid Filter theme={null}
  {
    "error": "Filter group must have at least one condition or nested group",
    "code": "empty_filter_group"
  }
  ```

  ```json 404 — Not Found theme={null}
  {
    "error": "Audience not found",
    "code": "not_found"
  }
  ```

  ```json 401 — Unauthorized theme={null}
  {
    "error": "Invalid credentials",
    "code": "invalid_credentials"
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code                       | Description                                                                |
| ----------- | -------------------------------- | -------------------------------------------------------------------------- |
| 400         | `name_too_long`                  | Name exceeds 255 characters                                                |
| 400         | `source_list_not_found`          | A sending list ID in `source_lists` does not exist                         |
| 400         | `invalid_group_operator`         | Filter group `operator` must be `AND` or `OR`                              |
| 400         | `empty_filter_group`             | Filter group contains no conditions or nested groups                       |
| 400         | `invalid_condition_type`         | Condition type is not one of the seven valid types                         |
| 400         | `invalid_time_field`             | Time condition `field` is not valid                                        |
| 400         | `invalid_time_operator`          | Time condition `operator` is not valid                                     |
| 400         | `invalid_time_unit`              | Time condition `unit` must be `days`, `hours`, or `minutes`                |
| 400         | `missing_time_value`             | Time condition is missing `value` or `unit`                                |
| 400         | `invalid_count_field`            | Count condition `field` is not valid                                       |
| 400         | `invalid_count_operator`         | Count condition `operator` is not valid                                    |
| 400         | `missing_count_value`            | Count condition is missing `value`                                         |
| 400         | `missing_custom_field_name`      | Custom field condition is missing `field`                                  |
| 400         | `invalid_custom_field_operator`  | Custom field condition `operator` is not valid                             |
| 400         | `missing_custom_field_value`     | Custom field condition is missing `value`                                  |
| 400         | `invalid_carrier_operator`       | Carrier condition `operator` is not valid                                  |
| 400         | `missing_carrier_value`          | Carrier condition is missing `value`                                       |
| 400         | `invalid_timezone_operator`      | Timezone condition `operator` is not valid                                 |
| 400         | `missing_timezone_value`         | Timezone condition is missing `value`                                      |
| 400         | `invalid_revenue_field`          | Revenue condition `field` is not valid                                     |
| 400         | `invalid_revenue_operator`       | Revenue condition `operator` is not valid                                  |
| 400         | `missing_revenue_value`          | Revenue condition is missing `value`                                       |
| 400         | `invalid_phone_numbers_operator` | Phone numbers condition `operator` is not `in` or `not_in`                 |
| 400         | `missing_phone_numbers_value`    | Phone numbers condition `value` is missing or an empty list                |
| 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. |
| 404         | `not_found`                      | No audience exists with the specified ID                                   |

## Next Steps

<CardGroup cols={2}>
  <Card title="Creating Audiences" icon="users" href="/guides/audiences/creating-audiences">
    Manage audience segments
  </Card>

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