Source: https://datafa.st/docs/api/account/goal-customizations/list
Markdown source: https://datafa.st/docs/api/account/goal-customizations/list.md
Description: List saved goal display customizations and allowed colors.

# List goal customizations

`GET https://datafa.st/api/v1/admin/websites/{websiteId}/goals/customizations`

List saved display metadata for goals on one website. Use `goalName` to filter to one goal.

The response also includes `colors`, the allowed palette for update requests.

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

## Request

#### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | string | — | Website ObjectId. From [List websites](/docs/api/account/websites/list) (`_id` field). Example: `665f0b3c4d2e1a0012345678`. |

#### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `goalName` | string | No | Filter to one raw tracked goal name. Example: `signup_started`. |

## Response

Returns a JSON object with `status: "success"` and endpoint-specific fields in `data`.

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `data[].goalName` | string | Raw tracked goal name. |
| `data[].displayName` | string\|null | Custom display name. |
| `data[].color` | string\|null | Custom chart color. |
| `data[].description` | string\|null | Internal custom description. |
| `data[].updatedAt` | string\|null | Last update timestamp. |
| `colors[]` | object[] | Allowed color palette returned by list requests. |
| `colors[].color` | string | Allowed hex color. |
| `colors[].label` | string | Human-readable color label. |
| `colors[].family` | string | Color family used to avoid similar defaults. |

### Authentication

Use a `dft_` account token with `goals:read`.

A `df_` website API key for the same website can also call this route when the path `websiteId` matches the key's website. Write access with a `df_` key is capped at **member** level — owner-only actions such as [team management](/docs/api/account/team) require a `dft_` token and owner role.

### Errors

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 GET "https://datafa.st/api/v1/admin/websites/{websiteId}/goals/customizations" \
  -H "Authorization: Bearer dft_xxx"
```

### Success response

```json
{
  "status": "success",
  "data": [{
    "goalName": "signup_started",
    "displayName": "Signup started",
    "color": "#8dcdff",
    "description": "Visitor opened the signup flow",
    "updatedAt": "2026-05-21T00:00:00.000Z"
  }],
  "colors": [
    { "color": "#ef4444", "family": "red", "label": "Red" },
    { "color": "#8dcdff", "family": "blue", "label": "Sky" }
  ]
}
```