Source: https://datafa.st/docs/api/website/goals/delete
Markdown source: https://datafa.st/docs/api/website/goals/delete.md
Description: Delete custom goal events by visitor, goal name, or time range. Use this to clean up test data or comply with deletion requests.

# Delete goals

`DELETE https://datafa.st/api/v1/goals`

Delete custom goal events by visitor, goal name, or time range. Use this to clean up test data or comply with deletion requests.

Provide at least one filter. For bulk deletes without a visitor or goal name, `start` and `end` are **required** (note: this endpoint uses `start`/`end`, not `startAt`/`endAt`).

> **Related:** [Custom goals](/docs/custom-goals)

## Request

#### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | string | Required with dft_ | Required with a `dft_` account token on Website API routes. Omit with a `df_` website key. Example: `?websiteId=665f0b3c4d2e1a0012345678`. |
| `datafast_visitor_id` | string | No | Delete all goals for one visitor. Visitor UUID from the `datafast_visitor_id` cookie or tracking script. Example: `"a3ab2331-989f-4cfa-91c6-2461c9e3c6bd"`. Alias: `visitorId` on some endpoints. |
| `name` | string | No | Delete by goal name. Goal name stored lowercase; spaces → `_`. Allowed: `a-z`, `0-9`, `_`, `-`, `:`. Max 64 chars. Reserved: `identify`. Example: `"newsletter_signup"`. See [custom goals](/docs/custom-goals). |
| `start` | string | Conditional | ISO 8601 bounds for bulk delete. Example query: `start=2026-05-01T00:00:00Z&end=2026-05-19T23:59:59Z`. **Required together** when no other filter (transaction, visitor, or goal name) is provided. Note: uses `start`/`end`, not `startAt`/`endAt`. |
| `end` | string | Conditional | ISO 8601 end bound. Required with `start` for bulk deletes. |

#### Example queries

By goal name and range:

```http
DELETE /api/v1/goals?name=signup&start=2026-05-01T00:00:00Z&end=2026-05-19T23:59:59Z
```

Bulk delete (requires `start` + `end` only):

```http
DELETE /api/v1/goals?start=2026-05-01T00:00:00Z&end=2026-05-19T23:59:59Z
```

## Response

Returns a JSON object with `status: "success"` and endpoint-specific fields in `data` (and `pagination` when the endpoint is paginated).

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | `success`. |
| `data[].message` | string | Human-readable confirmation or status message for the operation. |
| `data[].datafast_visitor_id` | string | DataFast visitor UUID from the browser cookie or client SDK. Used to attach server-side events to a visitor journey. |
| `data[].goal_name` | string | Present when deleting by goal name. |
| `data[].timeRange.start` | string | Present for time range deletes. |
| `data[].timeRange.end` | string | Present for time range deletes. |

## Authentication

- **`df_` website API key:** The website is inferred from the key. You do not need a `websiteId` query parameter.
- **`dft_` account token:** Requires `goals:write` permission and `?websiteId=` on every request. The token must be allowed to access that website.

Read [authentication and scopes](/docs/api/authentication) for token creation, permission lists, and scoped tokens.

### Errors

**400** — No filter provided, invalid goal name, invalid visitor ID, or missing `start`/`end` for bulk delete.

**504** — Delete operation timed out. Retry with a smaller time range.

See [API errors](/docs/api#errors) for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

## Code examples

### Example request

```bash
curl -X DELETE "https://datafa.st/api/v1/goals?name=signup&start=2026-05-01T00:00:00Z&end=2026-05-19T23:59:59Z" \
  -H "Authorization: Bearer df_xxx"
```

### Success response

```json
{
  "status": "success",
  "data": [{
    "message": "Goal events deleted successfully within time range",
    "goal_name": "signup",
    "timeRange": {
      "start": "2026-05-01T00:00:00.000Z",
      "end": "2026-05-19T23:59:59.000Z"
    }
  }]
}
```