Update goal customization

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

Create or update display-only metadata for one tracked goal. This changes dashboard labels/colors, not the raw event name your tracker or API sends.

Send only fields you want to change. Pass null for displayName, color, or description to clear that one field.

Related: Custom goals

Request

Path parameters

websiteId

string

Website ObjectId. From List websites (_id field). Example: 665f0b3c4d2e1a0012345678.

Body parameters

goalName

string

required

Goal name stored lowercase; spaces → _. Allowed: a-z, 0-9, _, -, :. Max 64 chars. Reserved: identify. Example: "newsletter_signup". See custom goals.

displayName

string|null

Display-only label used in dashboard charts, tooltips, and CLI output. It does not change the raw tracked goal name. Max 80 characters. Example: "Signup started".

color

string|null

Hex color from the allowed DataFast goal palette. Get options from List goal customizations or datafast goals colors. Pass null to clear. Example: "#8dcdff".

description

string|null

Internal display description for your team. Not shown to end users and not used for tracking. Max 300 characters. Pass null to clear.

hidden

boolean

Hide or show the goal in dashboard goal lists. Defaults to false.

Example request body

{
  "goalName": "signup_started",
  "displayName": "Signup started",
  "color": "#8dcdff",
  "description": "Visitor opened the signup flow",
  "hidden": false
}

Response

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

Response fields

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[].hidden

boolean

Whether the goal is hidden in dashboard lists.

data[].updatedAt

string|null

Last update timestamp.

colors[]

object[]

Allowed color palette returned by list requests.

Authentication

Use a dft_ account token with goals:write.

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 require a dft_ token and owner role.

Errors

400 — Invalid goal name, color not in the allowed palette, no fields provided, or text fields too long.

413 — Request body is larger than 4 KB.

See API errors for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

✍️ Something missing? Suggest features.

🤖 AI agent or LLM? Read this page as markdown

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

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