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.

Example request body

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

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[].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", "updatedAt": "2026-05-21T00:00:00.000Z" }], "colors": [ { "color": "#ef4444", "family": "red", "label": "Red" }, { "color": "#8dcdff", "family": "blue", "label": "Sky" } ] }