Create Goal

Endpoint

PUT /api/plugins/v1/goals

Creates a new goal or returns an existing goal if it already exists (upsert behavior). Goals are used to track conversions for custom events or pageviews.

Authentication

Requires a Plugins API token with write access.

string

required

Bearer token for authentication

Authorization: Bearer YOUR_API_TOKEN

Request Body

The request body accepts either a single goal or multiple goals (for bulk creation).

Single Goal Creation

string

required

Type of goal to createOptions:

Goal.CustomEvent - Track custom events
Goal.Pageview - Track pageview conversions
Goal.Revenue - Track revenue goals (requires Business plan)

object

required

Goal configuration object (structure varies by goal_type)

Custom Event Goal

string

required

Name of the custom event to trackRequirements:

Maximum length: 120 characters
Cannot be engagement (reserved)
Will be trimmed of leading/trailing whitespace

Examples: Signup, Purchase, Download

object

Custom properties filter for the goal (up to 3 properties)Requirements:

Maximum 3 properties per goal
Keys: 1-300 characters
Values: 1-2000 characters
Both keys and values must be strings

Example:

{
  "plan": "premium"
}

Pageview Goal

string

required

Page path to track as a goalRequirements:

Must start with /
Will be trimmed of leading/trailing whitespace
Leading slash is automatically added if missing

Examples: /pricing, /blog/*, /thank-you

object

Custom properties filter for the goal (up to 3 properties)

Revenue Goal (Business Plan)

string

required

Name of the revenue event to track

string

required

Currency code for revenue trackingRequirements:

Must be a valid ISO 4217 currency code
Cannot be changed once the goal is created
Each event name can only have one currency

Examples: USD, EUR, GBP

object

Custom properties filter for the goal (up to 3 properties)

Bulk Goal Creation

array

Array of goal objects (maximum 8 goals)Each goal object follows the same structure as single goal creation.

Response

array

Array of created or retrieved goals

string

Type of goal: Goal.CustomEvent, Goal.Pageview, or Goal.Revenue

integer

Unique identifier for the goal

string

Human-readable display name for the goal

For custom events: same as event_name
For pageviews: “Visit ”

string

Event name (for custom event and revenue goals)

string

Page path (for pageview goals)

string

Currency code (for revenue goals)

object

Custom properties filter configuration

Status Codes

201 Created - Goal(s) created or retrieved successfully
400 Bad Request - Invalid request parameters
401 Unauthorized - Missing or invalid API token
402 Payment Required - Revenue goals require Business plan upgrade
422 Unprocessable Entity - Validation error

Examples

Create Custom Event Goal

curl -X PUT https://plausible.io/api/plugins/v1/goals \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goal_type": "Goal.CustomEvent",
    "goal": {
      "event_name": "Signup"
    }
  }'

const response = await fetch('https://plausible.io/api/plugins/v1/goals', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    goal_type: 'Goal.CustomEvent',
    goal: {
      event_name: 'Signup'
    }
  })
});

const data = await response.json();

import requests

response = requests.put(
    'https://plausible.io/api/plugins/v1/goals',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'goal_type': 'Goal.CustomEvent',
        'goal': {
            'event_name': 'Signup'
        }
    }
)

print(response.json())

Response:

{
  "goals": [
    {
      "goal_type": "Goal.CustomEvent",
      "goal": {
        "id": 123,
        "display_name": "Signup",
        "event_name": "Signup",
        "custom_props": {}
      }
    }
  ]
}

Create Pageview Goal

curl -X PUT https://plausible.io/api/plugins/v1/goals \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goal_type": "Goal.Pageview",
    "goal": {
      "path": "/thank-you"
    }
  }'

const response = await fetch('https://plausible.io/api/plugins/v1/goals', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    goal_type: 'Goal.Pageview',
    goal: {
      path: '/thank-you'
    }
  })
});

Response:

{
  "goals": [
    {
      "goal_type": "Goal.Pageview",
      "goal": {
        "id": 124,
        "display_name": "Visit /thank-you",
        "path": "/thank-you",
        "custom_props": {}
      }
    }
  ]
}

Create Goal with Custom Properties

curl -X PUT https://plausible.io/api/plugins/v1/goals \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goal_type": "Goal.CustomEvent",
    "goal": {
      "event_name": "Purchase",
      "custom_props": {
        "plan": "premium"
      }
    }
  }'

const response = await fetch('https://plausible.io/api/plugins/v1/goals', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    goal_type: 'Goal.CustomEvent',
    goal: {
      event_name: 'Purchase',
      custom_props: {
        plan: 'premium'
      }
    }
  })
});

Response:

{
  "goals": [
    {
      "goal_type": "Goal.CustomEvent",
      "goal": {
        "id": 125,
        "display_name": "Purchase",
        "event_name": "Purchase",
        "custom_props": {
          "plan": "premium"
        }
      }
    }
  ]
}

Create Revenue Goal (Business Plan)

curl -X PUT https://plausible.io/api/plugins/v1/goals \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goal_type": "Goal.Revenue",
    "goal": {
      "event_name": "Purchase",
      "currency": "USD"
    }
  }'

const response = await fetch('https://plausible.io/api/plugins/v1/goals', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    goal_type: 'Goal.Revenue',
    goal: {
      event_name: 'Purchase',
      currency: 'USD'
    }
  })
});

Response:

{
  "goals": [
    {
      "goal_type": "Goal.Revenue",
      "goal": {
        "id": 126,
        "display_name": "Purchase",
        "event_name": "Purchase",
        "currency": "USD",
        "custom_props": {}
      }
    }
  ]
}

Bulk Create Goals

curl -X PUT https://plausible.io/api/plugins/v1/goals \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goals": [
      {
        "goal_type": "Goal.CustomEvent",
        "goal": {
          "event_name": "Signup"
        }
      },
      {
        "goal_type": "Goal.Pageview",
        "goal": {
          "path": "/pricing"
        }
      }
    ]
  }'

const response = await fetch('https://plausible.io/api/plugins/v1/goals', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    goals: [
      {
        goal_type: 'Goal.CustomEvent',
        goal: { event_name: 'Signup' }
      },
      {
        goal_type: 'Goal.Pageview',
        goal: { path: '/pricing' }
      }
    ]
  })
});

Error Responses

Validation Error

{
  "errors": {
    "event_name": ["can't be blank"],
    "currency": ["is invalid"]
  }
}

Maximum Goals Reached

{
  "errors": {
    "event_name": ["Maximum number of goals reached"]
  }
}

Note: Each site can have a maximum of 1,000 goals.

Upgrade Required (Revenue Goals)

{
  "error": "Revenue Goals is part of the Plausible Business plan. To get access to this feature, please upgrade your account."
}

Currency Mismatch

{
  "errors": {
    "event_name": ["'Purchase' (with currency: EUR) has already been taken"]
  }
}

This error occurs when trying to create a revenue goal with a different currency for an event name that already exists with another currency.

Notes

Goals are created with upsert behavior - if a goal already exists, it will be returned instead of creating a duplicate
Display names are automatically generated: event name for custom events, “Visit ” for pageviews
Leading and trailing whitespace in event names and paths is automatically trimmed
Pageview goals automatically get a leading / if not provided
Revenue goals cannot be created for consolidated views
Once created, a revenue goal’s currency cannot be changed
Custom properties require the Props feature (available on certain plans)

List Goals - Retrieve all goals for a site
Delete Goal - Remove a goal by ID
Custom Events - Send custom events to track against goals

Overview

Stats API

Sites API

Events API

Goals API

Endpoint

Authentication

Request Body

Single Goal Creation

Custom Event Goal

Pageview Goal

Revenue Goal (Business Plan)

Bulk Goal Creation

Response

Status Codes

Examples

Create Custom Event Goal

Create Pageview Goal

Create Goal with Custom Properties

Create Revenue Goal (Business Plan)

Bulk Create Goals

Error Responses

Validation Error

Maximum Goals Reached

Upgrade Required (Revenue Goals)

Currency Mismatch

Notes

​Endpoint

​Authentication

​Request Body

​Single Goal Creation

​Custom Event Goal

​Pageview Goal

​Revenue Goal (Business Plan)

​Bulk Goal Creation

​Response

​Status Codes

​Examples

​Create Custom Event Goal

​Create Pageview Goal

​Create Goal with Custom Properties

​Create Revenue Goal (Business Plan)

​Bulk Create Goals

​Error Responses

​Validation Error

​Maximum Goals Reached

​Upgrade Required (Revenue Goals)

​Currency Mismatch

​Notes

​Related Endpoints

Endpoint

Authentication

Request Body

Single Goal Creation

Custom Event Goal

Pageview Goal

Revenue Goal (Business Plan)

Bulk Goal Creation

Response

Status Codes

Examples

Create Custom Event Goal

Create Pageview Goal

Create Goal with Custom Properties

Create Revenue Goal (Business Plan)

Bulk Create Goals

Error Responses

Validation Error

Maximum Goals Reached

Upgrade Required (Revenue Goals)

Currency Mismatch

Notes

Related Endpoints