Query analytics

curl --request POST \
  --url https://app.sagepilot.ai/platform-api/v1/analytics/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dataset": "<string>",
  "measures": [
    "<string>"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({dataset: '<string>', measures: ['<string>']})
};

fetch('https://app.sagepilot.ai/platform-api/v1/analytics/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.sagepilot.ai/platform-api/v1/analytics/query"

payload = {
    "dataset": "<string>",
    "measures": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "dataset": "tickets",
  "rows": [],
  "summary": {
    "ticket_count": 1128
  },
  "meta": {
    "applied_filters": {
      "channel_ids": [],
      "channel_kinds": [],
      "statuses": [],
      "priorities": [],
      "assignee_ids": [],
      "assignee_types": [],
      "team_ids": [],
      "tag_ids": [],
      "excluded_tag_ids": [],
      "queue_statuses": [],
      "inferred_csat_scores": [],
      "user_csat_scores": [],
      "custom_fields": [],
      "score_sources": [],
      "actor_ids": [],
      "actor_types": [],
      "entity_types": []
    },
    "grain": null,
    "timezone": "UTC",
    "time_anchor": "created_at",
    "requested_measures": [
      "ticket_count"
    ],
    "requested_dimensions": [],
    "generated_at": "2026-05-29T16:16:53.572328Z",
    "cursor": null
  }
}

POST

platform-api

analytics

query

Query analytics

curl --request POST \
  --url https://app.sagepilot.ai/platform-api/v1/analytics/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dataset": "<string>",
  "measures": [
    "<string>"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({dataset: '<string>', measures: ['<string>']})
};

fetch('https://app.sagepilot.ai/platform-api/v1/analytics/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.sagepilot.ai/platform-api/v1/analytics/query"

payload = {
    "dataset": "<string>",
    "measures": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "dataset": "tickets",
  "rows": [],
  "summary": {
    "ticket_count": 1128
  },
  "meta": {
    "applied_filters": {
      "channel_ids": [],
      "channel_kinds": [],
      "statuses": [],
      "priorities": [],
      "assignee_ids": [],
      "assignee_types": [],
      "team_ids": [],
      "tag_ids": [],
      "excluded_tag_ids": [],
      "queue_statuses": [],
      "inferred_csat_scores": [],
      "user_csat_scores": [],
      "custom_fields": [],
      "score_sources": [],
      "actor_ids": [],
      "actor_types": [],
      "entity_types": []
    },
    "grain": null,
    "timezone": "UTC",
    "time_anchor": "created_at",
    "requested_measures": [
      "ticket_count"
    ],
    "requested_dimensions": [],
    "generated_at": "2026-05-29T16:16:53.572328Z",
    "cursor": null
  }
}

{
  "dataset": "tickets",
  "rows": [],
  "summary": {
    "ticket_count": 1128
  },
  "meta": {
    "applied_filters": {
      "channel_ids": [],
      "channel_kinds": [],
      "statuses": [],
      "priorities": [],
      "assignee_ids": [],
      "assignee_types": [],
      "team_ids": [],
      "tag_ids": [],
      "excluded_tag_ids": [],
      "queue_statuses": [],
      "inferred_csat_scores": [],
      "user_csat_scores": [],
      "custom_fields": [],
      "score_sources": [],
      "actor_ids": [],
      "actor_types": [],
      "entity_types": []
    },
    "grain": null,
    "timezone": "UTC",
    "time_anchor": "created_at",
    "requested_measures": [
      "ticket_count"
    ],
    "requested_dimensions": [],
    "generated_at": "2026-05-29T16:16:53.572328Z",
    "cursor": null
  }
}

Use this endpoint to run analytics queries for a granted dataset. Query results can be returned as summary totals or grouped rows. For campaign or journey attribution, estimated ROAS, and delivery by template category, use the journey and campaign analytics guide. Discover supported combinations with the analytics catalog.

Required access

Authentication	Scope	Dataset grant
API client v2	`analytics.query`	The dataset used in the request body, such as `tickets`, `messages`, `outbound_messages`, `marketing_attribution`, `csat`, or `workforce_activity`.

Body

string

required

Dataset to query. For example, tickets, messages, outbound_messages, marketing_attribution, csat, or workforce_activity.

string[]

required

Measures to calculate. For example, ["ticket_count", "open_ticket_count"] for the tickets dataset or ["message_count", "customer_message_count"] for the messages dataset.

string[]

Optional dimensions to group results. For example, ["channel_kind"], ["priority"], or ["day_of_week", "hour_of_day"].

object

Optional filter object. For example, { "channel_ids": ["<channel_id>"], "statuses": ["open"] }. For channel, agent, pilot, team, or workspace IDs, see Resource IDs.

string[]

Campaign UUIDs, up to 100. Supported by marketing_attribution and outbound_messages. Resolve names with analytics member lookup. An empty array imposes no restriction.

string[]

Journey UUIDs, up to 100. Supported by marketing_attribution and outbound_messages. With campaign IDs, attribution selects either requested entity type; outbound queries require both filters to match each message.

string[]

For marketing_attribution, use campaign, journey, or both. Defaults to both. This filter also applies when you specify entity IDs.

string

For marketing_attribution, use delivery, read, or clicked. Omit to use your workspace attribution setting.

integer

Attribution lookback override for marketing_attribution, from 1 to 8760 hours. Omit to use your workspace setting. This is separate from the reporting period in time.

string[]

For outbound category queries only: MARKETING, UTILITY, AUTHENTICATION, or UNKNOWN. Requires a supported template_category grouping. Values are case-sensitive.

object

Optional time window. Include this for trend queries or date-bounded summaries.

string

ISO start timestamp. For example, 2026-05-01T00:00:00.000Z.

string

ISO end timestamp. For example, 2026-05-29T23:59:59.999Z.

string

Timezone used to group time buckets. For example, Asia/Kolkata or UTC. Explicit offsets in start/end timestamps determine the reporting boundaries; timestamps without an offset are treated as UTC.

string

Time grain for grouped trend results. Use day, week, or month.

string

Timestamp field used for the query window. For example, created_at, closed_at, message_created_at, sent_at, or order_created_at.

object

Optional business-hours configuration for business-hours duration measures.

string

Business-hours timezone. For example, Asia/Kolkata.

string

Local business day start time. For example, 09:00.

string

Local business day end time. For example, 18:00.

integer[]

Working days as weekday numbers. For example, [1, 2, 3, 4, 5] for Monday through Friday.

string

Response shape, where supported by the chosen query. Use summary for aggregate totals or rows for grouped rows. Marketing attribution and template-category queries return rows and reject summary.

object[]

Optional sort instructions. For example, [{ "field": "ticket_count", "direction": "desc" }].

string

Field to sort by, usually a requested measure or dimension.

string

Sort direction. Use asc or desc.

integer

Maximum number of rows to return, from 1 to 1000. Marketing attribution defaults to 1000 rows per page. Category queries apply a limit without pagination; omit it when you need all matching buckets.

string

For marketing attribution, use meta.cursor from the previous response with the same filters, measures, and time settings. Stop when it is null. Template-category queries reject cursors.

Notes

This endpoint uses API client v2 credentials. See API client v2.
Marketing attribution and template-category queries require a time window and reject reversed ranges, unknown timezones, business_hours, and aggregation. Marketing attribution also rejects custom sort.
Unsupported or misspelled filters on these datasets return an error. A missing scope or dataset grant returns 403; invalid query combinations return 400, and malformed request fields return 422.

​Required access

​Body

​Notes

Required access

Body

Notes