List Goals

Endpoint

GET /api/plugins/v1/goals

Retrieves a paginated list of all goals configured for your site. Goals are returned in descending order by ID (newest first).

Authentication

Requires a Plugins API token with read access.

string

required

Bearer token for authentication

Authorization: Bearer YOUR_API_TOKEN

Query Parameters

integer

default:"10"

Maximum number of goals to return per pageMaximum: 1000 (also the maximum total goals per site)

string

Cursor value for forward paginationReturned in the pagination metadata of the previous response.

string

Cursor value for backward paginationReturned in the pagination metadata of the previous response.

Response

array

Array of goal objects

string

Type of goalValues:

Goal.CustomEvent - Custom event goal
Goal.Pageview - Pageview goal
Goal.Revenue - Revenue goal (Business plan)

integer

Unique identifier for the goal

string

Human-readable display name

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

string

Event name (for custom event and revenue goals only)

string

Page path (for pageview goals only)

string

Currency code (for revenue goals only)Examples: USD, EUR, GBP

object

Custom properties filter configuration (if any)

object

Pagination metadata

string

Cursor for fetching the next page (null if no more pages)

string

Cursor for fetching the previous page (null if on first page)

integer

The limit used for this request

Status Codes

200 OK - Goals retrieved successfully
401 Unauthorized - Missing or invalid API token

Examples

List All Goals

curl -X GET "https://plausible.io/api/plugins/v1/goals" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const response = await fetch('https://plausible.io/api/plugins/v1/goals', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
});

const data = await response.json();
console.log(data.goals);

import requests

response = requests.get(
    'https://plausible.io/api/plugins/v1/goals',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)

goals = response.json()
print(goals)

Response:

{
  "goals": [
    {
      "goal_type": "Goal.CustomEvent",
      "goal": {
        "id": 123,
        "display_name": "Signup",
        "event_name": "Signup",
        "custom_props": {}
      }
    },
    {
      "goal_type": "Goal.Pageview",
      "goal": {
        "id": 122,
        "display_name": "Visit /pricing",
        "path": "/pricing",
        "custom_props": {}
      }
    },
    {
      "goal_type": "Goal.Revenue",
      "goal": {
        "id": 121,
        "display_name": "Purchase",
        "event_name": "Purchase",
        "currency": "USD",
        "custom_props": {}
      }
    }
  ],
  "meta": {
    "after": null,
    "before": null,
    "limit": 10
  }
}

List Goals with Pagination

curl -X GET "https://plausible.io/api/plugins/v1/goals?limit=5" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const response = await fetch(
  'https://plausible.io/api/plugins/v1/goals?limit=5',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN'
    }
  }
);

const data = await response.json();

// Fetch next page if available
if (data.meta.after) {
  const nextPage = await fetch(
    `https://plausible.io/api/plugins/v1/goals?limit=5&after=${data.meta.after}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN'
      }
    }
  );
}

import requests

response = requests.get(
    'https://plausible.io/api/plugins/v1/goals',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    params={'limit': 5}
)

data = response.json()

# Fetch next page if available
if data['meta']['after']:
    next_response = requests.get(
        'https://plausible.io/api/plugins/v1/goals',
        headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
        params={
            'limit': 5,
            'after': data['meta']['after']
        }
    )

Response:

{
  "goals": [
    {
      "goal_type": "Goal.CustomEvent",
      "goal": {
        "id": 125,
        "display_name": "Download",
        "event_name": "Download",
        "custom_props": {}
      }
    },
    {
      "goal_type": "Goal.CustomEvent",
      "goal": {
        "id": 124,
        "display_name": "Signup",
        "event_name": "Signup",
        "custom_props": {}
      }
    },
    {
      "goal_type": "Goal.Pageview",
      "goal": {
        "id": 123,
        "display_name": "Visit /pricing",
        "path": "/pricing",
        "custom_props": {}
      }
    },
    {
      "goal_type": "Goal.CustomEvent",
      "goal": {
        "id": 122,
        "display_name": "Purchase",
        "event_name": "Purchase",
        "custom_props": {
          "plan": "premium"
        }
      }
    },
    {
      "goal_type": "Goal.Revenue",
      "goal": {
        "id": 121,
        "display_name": "Purchase",
        "event_name": "Purchase",
        "currency": "EUR",
        "custom_props": {}
      }
    }
  ],
  "meta": {
    "after": "eyJpZCI6MTIxfQ==",
    "before": null,
    "limit": 5
  }
}

Fetch All Goals (Iterating Pages)

async function fetchAllGoals(apiToken) {
  const allGoals = [];
  let after = null;
  
  do {
    const url = new URL('https://plausible.io/api/plugins/v1/goals');
    if (after) url.searchParams.set('after', after);
    url.searchParams.set('limit', '100');
    
    const response = await fetch(url, {
      headers: { 'Authorization': `Bearer ${apiToken}` }
    });
    
    const data = await response.json();
    allGoals.push(...data.goals);
    after = data.meta.after;
  } while (after);
  
  return allGoals;
}

const goals = await fetchAllGoals('YOUR_API_TOKEN');
console.log(`Total goals: ${goals.length}`);

import requests

def fetch_all_goals(api_token):
    all_goals = []
    after = None
    
    while True:
        params = {'limit': 100}
        if after:
            params['after'] = after
        
        response = requests.get(
            'https://plausible.io/api/plugins/v1/goals',
            headers={'Authorization': f'Bearer {api_token}'},
            params=params
        )
        
        data = response.json()
        all_goals.extend(data['goals'])
        after = data['meta']['after']
        
        if not after:
            break
    
    return all_goals

goals = fetch_all_goals('YOUR_API_TOKEN')
print(f'Total goals: {len(goals)}')

Goal Types

Custom Event Goal

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

Pageview Goal

{
  "goal_type": "Goal.Pageview",
  "goal": {
    "id": 124,
    "display_name": "Visit /pricing",
    "path": "/pricing",
    "custom_props": {}
  }
}

Revenue Goal (Business Plan)

{
  "goal_type": "Goal.Revenue",
  "goal": {
    "id": 125,
    "display_name": "Purchase",
    "event_name": "Purchase",
    "currency": "USD",
    "custom_props": {}
  }
}

Goal with Custom Properties

{
  "goal_type": "Goal.CustomEvent",
  "goal": {
    "id": 126,
    "display_name": "Purchase",
    "event_name": "Purchase",
    "custom_props": {
      "plan": "premium",
      "method": "stripe"
    }
  }
}

Notes

Goals are returned in descending order by ID (newest first)
Maximum 1,000 goals per site
Use pagination for sites with many goals
Goals with custom properties require the Props feature
Revenue goals are only available on the Business plan
The custom_props field is always present but may be an empty object

Create Goal - Create a new goal
Delete Goal - Remove a goal

Overview

Stats API

Sites API

Events API

Goals API

Endpoint

Authentication

Query Parameters

Response

Status Codes

Examples

List All Goals

Fetch All Goals (Iterating Pages)

Goal Types

Custom Event Goal

Pageview Goal

Revenue Goal (Business Plan)

Goal with Custom Properties

Notes

​Endpoint

​Authentication

​Query Parameters

​Response

​Status Codes

​Examples

​List All Goals

​List Goals with Pagination

​Fetch All Goals (Iterating Pages)

​Goal Types

​Custom Event Goal

​Pageview Goal

​Revenue Goal (Business Plan)

​Goal with Custom Properties

​Notes

​Related Endpoints

Endpoint

Authentication

Query Parameters

Response

Status Codes

Examples

List All Goals

List Goals with Pagination

Fetch All Goals (Iterating Pages)

Goal Types

Custom Event Goal

Pageview Goal

Revenue Goal (Business Plan)

Goal with Custom Properties

Notes

Related Endpoints