Skip to main content

​
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.
​
Authorization
string
required
Bearer token for authentication
Authorization: Bearer YOUR_API_TOKEN

​
Query Parameters

​
limit
integer
default:"10"
Maximum number of goals to return per pageMaximum: 1000 (also the maximum total goals per site)
​
after
string
Cursor value for forward paginationReturned in the pagination metadata of the previous response.
​
before
string
Cursor value for backward paginationReturned in the pagination metadata of the previous response.

​
Response

​
goals
array
Array of goal objects
​
goals[].goal_type
string
Type of goalValues:
  • Goal.CustomEvent - Custom event goal
  • Goal.Pageview - Pageview goal
  • Goal.Revenue - Revenue goal (Business plan)
​
goals[].goal.id
integer
Unique identifier for the goal
​
goals[].goal.display_name
string
Human-readable display name
  • For custom events: same as event_name
  • For pageviews: “Visit ”
​
goals[].goal.event_name
string
Event name (for custom event and revenue goals only)
​
goals[].goal.path
string
Page path (for pageview goals only)
​
goals[].goal.currency
string
Currency code (for revenue goals only)Examples: USD, EUR, GBP
​
goals[].goal.custom_props
object
Custom properties filter configuration (if any)
​
meta
object
Pagination metadata
​
meta.after
string
Cursor for fetching the next page (null if no more pages)
​
meta.before
string
Cursor for fetching the previous page (null if on first page)
​
meta.limit
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"
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"
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}`);

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us