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

# Clear History

> Clear imported historical data from your account.

Permanently delete imported historical data from your account. You can selectively clear sends, clicks, and/or revenue records.

<Info>
  **Important scoping differences:**

  * **Sends**: Only records where `imported=true` are cleared. Records from normal API sends or scheduled sends are never affected.
  * **Clicks**: Clicks are cleared based on the message IDs of imported send records. Only clicks associated with imported messages are removed.
  * **Revenue**: **All** revenue records for the account are cleared, not just those from imported messages. This includes revenue from live sends.
</Info>

<Warning>
  This is a **destructive operation** that cannot be undone. Cleared data is permanently deleted and cannot be recovered. Always verify your selection and consider using the `before_date` parameter to limit the scope of deletion.
</Warning>

## Authentication

<ParamField header="X-Api-Key" type="string" required>
  Your Trackly SMS API key. Format: `trk_[32-char-alphanumeric]`.
</ParamField>

## Body Parameters

<ParamField body="entities" type="array" required>
  An array of entity types to clear. Valid values: `sends`, `clicks`, `revenue`. You may include one or more entity types.
</ParamField>

<ParamField body="before_date" type="datetime">
  Only clear records with timestamps before this ISO 8601 datetime. If omitted, all matching records are cleared regardless of date.

  For `clicks`, `before_date` is applied to the parent send's (`MessageSent`) timestamp, not the click's own timestamp. Clicks are cleared based on the imported send records whose `timestamp` falls before `before_date`, regardless of when the click itself occurred.
</ParamField>

<ParamField body="confirm" type="boolean" required>
  Safety confirmation flag. Must be set to `true` to proceed with deletion. Requests with `confirm: false` or a missing `confirm` field are rejected.
</ParamField>

## Response Fields

<ResponseField name="success" type="boolean">
  Whether the clear operation completed successfully.
</ResponseField>

<ResponseField name="cleared" type="object">
  An object with counts of cleared records by entity type. Only includes entities that were requested.

  * `sends` (integer) -- Number of send records cleared.
  * `clicks` (integer) -- Number of click records cleared.
  * `revenue` (integer) -- Number of revenue records cleared.
</ResponseField>

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X DELETE https://api.tracklysms.com/api/v2/history/clear \
      -H "X-Api-Key: trk_your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "entities": ["sends", "clicks", "revenue"],
        "before_date": "2025-12-01T00:00:00Z",
        "confirm": true
      }'
    ```

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

    response = requests.delete(
        "https://api.tracklysms.com/api/v2/history/clear",
        headers={
            "X-Api-Key": "trk_your_api_key_here",
            "Content-Type": "application/json",
        },
        json={
            "entities": ["sends", "clicks", "revenue"],
            "before_date": "2025-12-01T00:00:00Z",
            "confirm": True,
        },
    )

    print(response.json())
    ```

    ```javascript Node.js theme={null}
    const response = await fetch("https://api.tracklysms.com/api/v2/history/clear", {
      method: "DELETE",
      headers: {
        "X-Api-Key": "trk_your_api_key_here",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        entities: ["sends", "clicks", "revenue"],
        before_date: "2025-12-01T00:00:00Z",
        confirm: true,
      }),
    });

    const data = await response.json();
    console.log(data);
    ```
  </CodeGroup>
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "success": true,
    "cleared": {
      "sends": 150,
      "clicks": 45,
      "revenue": 32
    }
  }
  ```

  ```json 200 - Partial Clear theme={null}
  {
    "success": true,
    "cleared": {
      "sends": 150
    }
  }
  ```

  ```json 400 - Missing Confirmation theme={null}
  {
    "error": "confirm must be true",
    "code": "confirm_required"
  }
  ```

  ```json 400 - Invalid Entities theme={null}
  {
    "error": "Invalid entities: orders. Valid: sends, clicks, revenue",
    "code": "invalid_entities"
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code         | Description                                                                      |
| ----------- | ------------------ | -------------------------------------------------------------------------------- |
| 400         | `missing_entities` | The `entities` field is required and must be a non-empty array.                  |
| 400         | `confirm_required` | The `confirm` field must be set to `true` to proceed.                            |
| 400         | `invalid_entities` | One or more entity types are not valid. Must be `sends`, `clicks`, or `revenue`. |

Authenticated requests can also fail with `401 invalid_credentials`, `403 account_suspended`, or `429 rate_limited` — see [Error Codes](/api-reference/v2/error-codes).

## Next Steps

<CardGroup cols={2}>
  <Card title="Reporting Overview" icon="chart-bar" href="/guides/reporting/overview">
    Understand your analytics
  </Card>

  <Card title="Bulk Create Contacts" icon="users" href="/api-reference/v2/contacts/bulk-create">
    Re-import after clearing
  </Card>
</CardGroup>