DocumentationGuidesAPI ReferenceCloudv2 🡕

Reports

Using reports throught the api.

Endpoints

GET /api/reports
POST /api/reports
GET /api/reports/:reportId
POST /api/reports/:reportId
DELETE /api/reports/:reportId
POST /api/reports/attribution
POST /api/reports/breakdown
POST /api/reports/funnel
POST /api/reports/goals
POST /api/reports/journey
POST /api/reports/retention
POST /api/reports/revenue
POST /api/reports/utm

Filters

All reports can now be filtered with the filters property in the request body.

Parameters

  • path: (string | optional) Name of URL.
  • referrer: (string | optional) Name of referrer.
  • title: (string | optional) Name of page title.
  • query: (string | optional) Name of query parameter.
  • browser: (string | optional) Name of browser.
  • os: (string | optional) Name of operating system.
  • device: (string | optional) Name of device (ex. Mobile)
  • country: (string | optional) Name of country.
  • region: (string | optional) Name of region/state/province.
  • city: (string | optional) Name of city.
  • hostname: (string | optional) Name of hostname.
  • tag: (string | optional) Name of tag.
  • segment: (uuid | optional) UUID of segment.
  • cohort: (uuid | optional) UUID of cohort.

Request body

{
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "attribution",
  "filters": { "os": "Mac OS", "device": "desktop" },
  "parameters": {
    "startDate": "2025-10-19T07:00:00.000Z",
    "endDate": "2025-10-26T06:59:59.999Z",
    "timezone": "America/Los_Angeles",
    "model": "first-click",
    "type": "path",
    "step": "/"
  }
}

GET /api/reports

Get all reports by website ID.

Parameters

  • websiteId : (string) Your website id.
  • type: (string) Report type (attribution| breakdown| funnel| goal| journey| retention| revenue| utm).
  • page: (optional number, default 1) Determines page.
  • pageSize: (optional string) Determines how many results to return.

Sample response

{
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "type": "goal",
      "name": "Visited /pricing",
      "description": "Test",
      "parameters": {
        "type": "path",
        "value": "/pricing"
      },
      "createdAt": "2025-07-23T17:28:55.192Z",
      "updatedAt": "2025-10-07T07:46:57.918Z"
    },
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "type": "goal",
      "name": "Triggered live-demo-button",
      "description": "",
      "parameters": {
        "type": "event",
        "value": "live-demo-button"
      },
      "createdAt": "2025-10-07T07:46:24.120Z",
      "updatedAt": "2025-10-07T07:46:24.120Z"
    }
  ],
  "count": 2,
  "page": 1,
  "pageSize": 20
}

POST /api/reports

Creates a report.

Parameters

  • websiteId : (string) Your website id.
  • type: (string) Report type attribution | breakdown | funnel | goal | journey | retention | revenue | utm.
  • name: (string) Name of report.
  • description: (string | optional) Description of report.
  • parameters: (object) Parameters for report.

Request body

{
  "name": "Triggered Login-button ",
  "parameters": { "type": "event", "value": "login-button-header" },
  "type": "goal",
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Sample response

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "goal",
  "name": "Triggered Login-button ",
  "description": "",
  "parameters": {
    "type": "event",
    "value": "login-button-header"
  },
  "createdAt": "2025-10-14T00:12:33.203Z",
  "updatedAt": "2025-10-14T00:12:33.203Z"
}

GET /api/reports/:reportId

Gets a report by ID.

Sample response

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "goal",
  "name": "Triggered Login-button ",
  "description": "",
  "parameters": {
    "type": "event",
    "value": "login-button-header"
  },
  "createdAt": "2025-10-14T00:12:33.203Z",
  "updatedAt": "2025-10-14T00:12:33.203Z"
}

POST /api/reports/:reportId

Updates a report.

Parameters

  • websiteId : (string) Your website id.
  • type: (string) Report type attribution | breakdown | funnel | goal | journey | retention | revenue | utm.
  • name: (string) Name of report.
  • description: (string | optional) Description of report.
  • parameters: (object) Parameters for report.

Request body

{
  "name": "Triggered Login-button ",
  "parameters": { "type": "event", "value": "login-button-header" },
  "type": "goal",
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Sample response

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "goal",
  "name": "Triggered Login-button ",
  "description": "",
  "parameters": {
    "type": "event",
    "value": "login-button-header"
  },
  "createdAt": "2025-10-14T00:12:33.203Z",
  "updatedAt": "2025-10-14T00:12:33.203Z"
}

DELETE /api/reports/:reportId

Deletes a report.

Sample response

{
  "ok": true
}

POST /api/reports/attribution

See how users engage with your marketing and what drives conversions.

Parameters

  • websiteId : (string) Your website id.
  • type: (string) Report type (attribution| breakdown| funnel| goal| journey| retention| revenue| utm).
  • filters: Can accept filter parameters.
  • startDate : (number) Date (in ms) of start date.
  • endDate : (number) Date (in ms) of end date.
  • model : (string) Attribution model (firstClick | lastClick).
  • type : (array) Conversion type (path | event).
  • step: (string) Conversion step

Request body

{
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "attribution",
  "filters": { "os": "Mac OS" },
  "parameters": {
    "startDate": "2025-10-19T07:00:00.000Z",
    "endDate": "2025-10-26T06:59:59.999Z",
    "model": "first-click",
    "type": "path",
    "step": "/"
  }
}

Sample response

{
  "referrer": [
    {
      "name": "google.com",
      "value": 30082
    },
    {
      "name": "chatgpt.com",
      "value": 1672
    }
  ],
  "paidAds": [
    {
      "name": "Facebook / Meta",
      "value": 106
    },
    {
      "name": "Google Ads",
      "value": 6
    }
  ],
  "utm_source": [
    {
      "name": "coolify.io",
      "value": 465
    },
    {
      "name": "chatgpt.com",
      "value": 338
    }
  ],
  "utm_medium": [
    {
      "name": "referral",
      "value": 75
    },
    {
      "name": "email",
      "value": 16
    }
  ],
  "utm_campaign": [
    {
      "name": "navigation",
      "value": 60
    },
    {
      "name": "website_analytics",
      "value": 8
    }
  ],
  "utm_content": [
    {
      "name": "comparison-page",
      "value": 1
    },
    {
      "name": "sidebar-cta",
      "value": 1
    }
  ],
  "utm_term": [
    {
      "name": "data analysis",
      "value": 1
    },
    {
      "name": "0_df65b6d7c8-e2c14ebdc7-59136105",
      "value": 1
    }
  ],
  "total": {
    "pageviews": 171481,
    "visitors": 104727,
    "visits": 138391
  }
}

POST /api/reports/breakdown

Dive deeper into your data by using segments and filters.

Parameters

  • websiteId : (string) Your website id.
  • type: (string) Report type (attribution| breakdown| funnel| goal| journey| retention| revenue| utm).
  • filters: Can accept filter parameters.
  • startDate : (number) Date (in ms) of start date.
  • endDate : (number) Date (in ms) of end date.
  • fields: (array) List of column fields.

Available Fields

path | title | query | referrer | browser | os | device | country | region | city | hostname| tag | event

Request body

{
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "breakdown",
  "filters": {},
  "parameters": {
    "startDate": "2025-07-23T07:00:00.000Z",
    "endDate": "2025-10-22T06:59:59.999Z",
    "fields": ["os", "country"]
  }
}

Sample response

[
  {
    "views": 37856,
    "visitors": 9229,
    "visits": 13145,
    "bounces": 8105,
    "totaltime": 12985151,
    "os": "Mac OS",
    "country": "US"
  },
  {
    "views": 24399,
    "visitors": 6628,
    "visits": 10673,
    "bounces": 7119,
    "totaltime": 21398417,
    "os": "Windows 10",
    "country": "US"
  },
  {
    "views": 21561,
    "visitors": 4916,
    "visits": 6532,
    "bounces": 3452,
    "totaltime": 22984512,
    "os": "Mac OS",
    "country": "DE"
  },
  {
    "views": 12977,
    "visitors": 2976,
    "visits": 4180,
    "bounces": 2440,
    "totaltime": 9962317,
    "os": "Windows 10",
    "country": "DE"
  }
]

POST /api/reports/funnel

Understand the conversion and drop-off rate of users.

Parameters

  • websiteId : (string) Your website id.
  • type: (string) Report type (attribution| breakdown| funnel| goal| journey| retention| revenue| utm).
  • filters: Can accept filter parameters.
  • startDate : (number) Date (in ms) of start date.
  • endDate : (number) Date (in ms) of end date.
  • steps : (array | Minumum two required) type of event (path | event) and conversion step.
  • window : (number) Window of days between funnel steps to be considered a conversion.

Request body

{
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "funnel",
  "filters": {},
  "parameters": {
    "startDate": "2025-07-23T07:00:00.000Z",
    "endDate": "2025-10-22T06:59:59.999Z",
    "steps": [
      { "type": "path", "value": "/" },
      { "type": "event", "value": "live-demo-button" }
    ],
    "window": 60
  }
}

Sample response

[
  {
    "type": "path",
    "value": "/",
    "visitors": 106594,
    "previous": 0,
    "dropped": 0,
    "dropoff": null,
    "remaining": 1
  },
  {
    "type": "event",
    "value": "live-demo-button",
    "visitors": 10269,
    "previous": 106594,
    "dropped": 96325,
    "dropoff": 0.9036624950747697,
    "remaining": 0.09633750492523031
  }
]

POST /api/reports/goals

Track your goals for pageviews and events.

Parameters

  • websiteId : (string) Your website id.
  • type: (string) Report type (attribution| breakdown| funnel| goal| journey| retention| revenue| utm).
  • filters: Can accept filter parameters.
  • startDate : (number) Date (in ms) of start date.
  • endDate : (number) Date (in ms) of end date.
  • type : (array) Conversion type (path | event).
  • value: (string) Conversion step value.

Request body

{
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "goal",
  "filters": {},
  "parameters": {
    "startDate": "2025-07-23T07:00:00.000Z",
    "endDate": "2025-10-22T06:59:59.999Z",
    "type": "event",
    "value": "live-demo-button"
  }
}

Sample response

{
  "num": 11935,
  "total": 50602
}

POST /api/reports/journey

Understand how users nagivate through your website.

Parameters

  • websiteId : (string) Your website id.
  • type: (string) Report type (attribution| breakdown| funnel| goal| journey| retention| revenue| utm).
  • filters: Can accept filter parameters.
  • startDate : (number) Date (in ms) of start date.
  • endDate : (number) Date (in ms) of end date.
  • steps: (number) Number of steps from 3 to 7
  • startStep : (string) Starting step URL or event name.
  • endStep : (string | optional) Ending step URL or event name.

Request body

{
  "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
  "type": "journey",
  "filters": {},
  "parameters": {
    "startDate": "2025-07-23T07:00:00.000Z",
    "endDate": "2025-10-22T06:59:59.999Z",
    "steps": 3,
    "startStep": "/",
    "endStep": "/pricing"
  }
}

Sample response

[
  {
    "items": ["/", "/pricing", null, null],
    "count": 6433
  },
  {
    "items": ["/", "live-demo-button", "/pricing", null],
    "count": 918
  },
  {
    "items": ["/", "/features", "/pricing", null],
    "count": 857
  },
  {
    "items": ["/", "/pricing", null],
    "count": 434
  },
  {
    "items": ["/", "/pricing", null],
    "count": 306
  },
  {
    "items": ["/", "/docs", "/pricing", null],
    "count": 257
  },
  {
    "items": ["/", "get-started-button", "/pricing", null],
    "count": 237
  },
  {
    "items": ["/", "login-button-header", "/pricing", null],
    "count": 102
  }
]

POST /api/reports/retention

Measure your website stickiness by tracking how often users return.

Parameters

  • websiteId : (string) Your website id.
  • type: (string) Report type (attribution| breakdown| funnel| goal| journey| retention| revenue| utm).
  • filters: Can accept filter parameters.
  • startDate : (number) Date (in ms) of start date.
  • endDate : (number) Date (in ms) of end date.
  • timezone: Timezone (ex. America/Los_Angeles).

Request body

{
  "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
  "type": "retention",
  "filters": {},
  "parameters": {
    "startDate": "2025-10-01T07:00:00.000Z",
    "endDate": "2025-11-01T06:59:59.999Z",
    "timezone": "America/Los_Angeles"
  }
}

Sample response

[
  {
    "date": "2025-10-01T07:00:00Z",
    "day": 0,
    "visitors": 1499,
    "returnVisitors": 1499,
    "percentage": 100
  },
  {
    "date": "2025-10-01T07:00:00Z",
    "day": 1,
    "visitors": 1499,
    "returnVisitors": 151,
    "percentage": 10.073382254836558
  },
  {
    "date": "2025-10-01T07:00:00Z",
    "day": 2,
    "visitors": 1499,
    "returnVisitors": 83,
    "percentage": 5.537024683122081
  },
  {
    "date": "2025-10-01T07:00:00Z",
    "day": 3,
    "visitors": 1499,
    "returnVisitors": 45,
    "percentage": 3.002001334222815
  }
]

POST /api/reports/revenue

Get currency for given range. Needed for Revenue and optional in Attribution reports.

Parameters

  • websiteId : (string) Your website id.
  • type: (string) Report type (attribution| breakdown| funnel| goal| journey| retention| revenue| utm).
  • filters: Can accept filter parameters.
  • startDate : (number) Date (in ms) of start date.
  • endDate : (number) Date (in ms) of end date.
  • timezone: Timezone (ex. America/Los_Angeles).
  • currency: (string) Currency code (ISO 4217).

Request body

{
  "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
  "type": "revenue",
  "filters": {},
  "parameters": {
    "startDate": "2025-07-23T07:00:00.000Z",
    "endDate": "2025-10-22T06:59:59.999Z",
    "timezone": "America/Los_Angeles",
    "currency": "USD"
  }
}

Sample response

{
  "chart": [
    {
      "x": "revenue-demo",
      "t": "2025-10-14T07:00:00Z",
      "y": 400
    },
    {
      "x": "revenue-demo",
      "t": "2025-10-15T07:00:00Z",
      "y": 480
    },
    {
      "x": "revenue-demo",
      "t": "2025-10-16T07:00:00Z",
      "y": 490
    }
  ],
  "country": [
    {
      "name": "US",
      "value": 1050
    },
    {
      "name": "FR",
      "value": 1040
    },
    {
      "name": "GB",
      "value": 720
    }
  ],
  "total": {
    "sum": 3870,
    "count": 131,
    "unique_count": 131,
    "average": 29.541984732824428
  }
}

POST /api/reports/utm

Track your campaigns through UTM parameters.

Parameters

  • websiteId : (string) Your website id.
  • type: (string) Report type (attribution| breakdown| funnel| goal| journey| retention| revenue| utm).
  • filters: Can accept filter parameters.
  • startDate : (number) Date (in ms) of start date.
  • endDate : (number) Date (in ms) of end date.

Request body

{
  "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
  "type": "utm",
  "filters": {},
  "parameters": {
    "startDate": "2025-10-14T07:00:00.000Z",
    "endDate": "2025-10-22T06:59:59.999Z"
  }
}

Sample response

{
  "utm_source": [
    {
      "utm": "chatgpt.com",
      "views": 341
    },
    {
      "utm": "coolify.io",
      "views": 235
    },
    {
      "utm": "openalternative.co",
      "views": 89
    },
    {
      "utm": "facebook",
      "views": 28
    }
  ],
  "utm_medium": [
    {
      "utm": "cpc",
      "views": 28
    },
    {
      "utm": "referral",
      "views": 26
    }
  ],
  "utm_campaign": [
    {
      "utm": "website_analytics",
      "views": 28
    },
    {
      "utm": "navigation",
      "views": 16
    }
  ],
  "utm_term": [
    {
      "utm": "0_df65b6d7c8-e2c14ebdc7-59136105",
      "views": 1
    }
  ],
  "utm_content": [
    {
      "utm": "comparison-page",
      "views": 1
    },
    {
      "utm": "sidebar-cta",
      "views": 1
    }
  ]
}

Realtime

Previous Page

Sessions

Next Page

On this page

FiltersGET /api/reportsPOST /api/reportsGET /api/reports/:reportIdPOST /api/reports/:reportIdDELETE /api/reports/:reportIdPOST /api/reports/attributionPOST /api/reports/breakdownPOST /api/reports/funnelPOST /api/reports/goalsPOST /api/reports/journeyPOST /api/reports/retentionPOST /api/reports/revenuePOST /api/reports/utm