Source: https://datafa.st/docs/api/account/tracked-goals
Markdown source: https://datafa.st/docs/api/account/tracked-goals.md
Description: List tracked goals and customize their dashboard display metadata.

# Goals API

Use these endpoints when building an agent or UI that needs to choose from existing goals before setting a KPI, creating an alert, creating a funnel, or customizing how a goal appears in charts.

Tracked goals are goals already seen in your analytics data, ordered by frequency. Goal customizations are display-only metadata: they change dashboard labels, colors, and internal descriptions, but they do **not** change the raw goal name your client or API sends.

Base path: `https://datafa.st/api/v1/admin`

| Endpoint | Method | Path | Permission | Purpose |
|---|---|---|---|---|
| [List tracked goals](/docs/api/account/tracked-goals/list) | GET | `/websites/{websiteId}/goals` | `settings:read` | List tracked goals ordered by frequency. Includes display customizations when saved |
| [List goal customizations](/docs/api/account/goal-customizations/list) | GET | `/websites/{websiteId}/goals/customizations` | `goals:read` | List saved custom display names, colors, and descriptions |
| [Update goal customization](/docs/api/account/goal-customizations/update) | PATCH | `/websites/{websiteId}/goals/customizations` | `goals:write` | Set display name, color, or description for one goal |
| [Delete goal customization](/docs/api/account/goal-customizations/delete) | DELETE | `/websites/{websiteId}/goals/customizations?goalName=...` | `goals:write` | Reset one goal's display metadata |

```sh
curl "https://datafa.st/api/v1/admin/websites/YOUR_WEBSITE_ID/goals" \
  -H "Authorization: Bearer dft_xxx"
```

## Customize a goal

```sh
curl -X PATCH "https://datafa.st/api/v1/admin/websites/YOUR_WEBSITE_ID/goals/customizations" \
  -H "Authorization: Bearer dft_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "goalName": "signup_started",
    "displayName": "Signup started",
    "color": "#8dcdff",
    "description": "Visitor opened the signup flow"
  }'
```

`goalName` must stay the raw tracked goal name. Keep sending that same value from your JavaScript tracker, SDK, or API.

To send goal events and query goal analytics, use [Goals](/docs/api/website/goals). Related CLI docs: [goals](/docs/cli-goals).

## Code examples

### Example request

```bash
curl "https://datafa.st/api/v1/admin/websites/YOUR_WEBSITE_ID/goals" \
  -H "Authorization: Bearer dft_xxx"
```

### Success response

```json
{
  "status": "success",
  "data": [
    {
      "name": "signup",
      "total": 128,
      "uv": 104,
      "conversionRate": 8.4,
      "eventType": "custom"
    }
  ]
}
```