Skip to Content

Report APIs

Overview

Report APIs return pre-aggregated analytics for a workspace. The portal Dashboard is built on them.

QueryWhat it returnsOne row per
convsReportConversation volume, response times and ratingsChannel, day and hour
agentsReportThe same metrics per human agentAgent, Channel and day
convStagesReportThe same metrics per lifecycle stageLifecycle stage, Channel and day
convTagsReportThe same metrics per conversation tagTag, Channel and day
messageReportMessage counts by delivery statusUTC hour
messageReportTodayLive message counts for the current UTC dayOne object

Broadcast usage has its own daily report on the Broadcasts page: Broadcast Report API.

Access: all report APIs need the MANAGE_CONVS permission (Owner, Admin, Manager). Workspace API keys can call them. Agent API keys are rejected because their Agent+ ceiling doesn’t include MANAGE_CONVS (see API Keys).

How conversation reports are built

convsReport, agentsReport, convStagesReport and convTagsReport are updated when a conversation ends: an agent or AI assistant ends it, or it is closed automatically after the workspace conversation TTL. Open conversations are not counted until they end. When a conversation ends, it is added to:

  • the convsReport row for its Channel and the hour it ended
  • the agentsReport row of the last human agent assigned to it. Conversations with no human agent, or whose agent was deleted, are skipped.
  • the convStagesReport row of the lifecycle stage it has when it ends. Conversations without a stage are skipped.
  • one convTagsReport row for each tag it has when it ends. A conversation with three tags counts in three rows.

Days and hours are calendar buckets of the server clock, which runs in UTC. A row exists only when at least one conversation ended in that bucket, so there are no zero rows.

Date range. startDate and endDate are inclusive and are compared to each row’s createdAt, the moment the row was first written (when the first conversation of that bucket ended). They are not rounded. To cover whole UTC days, send startDate as T00:00:00.000Z of the first day and endDate as T23:59:59.999Z of the last day. Rows come back newest first and are not paginated.

Metrics. These fields mean the same thing in all four reports:

FieldTypeDescription
conversationCountnumber

Conversations that ended in this bucket.

agentMessagesCountnumber

Business-side messages in those conversations: messages from agents, AI assistants and automated replies. Every message of each conversation is counted, not only the ones sent during the bucket. Internal notes are excluded.

clientMessageCountnumber

Messages the client sent in those conversations, counted over the whole conversation.

avgFirstResponseTimenumber

Average first response time in seconds: the time from the client's first message to the first business-side message, rounded to whole seconds (at least 1). Only conversations where the client wrote before the first reply are included. 0 when none qualify.

firstResponseConversationCountnumber

Number of conversations included in avgFirstResponseTime.

avgConversationTimenumber

Average conversation duration in seconds, from when the conversation was created to when it ended, across all conversationCount conversations.

newClientConvCountnumber

Conversations that were the client's first conversation in the workspace. Can be null.

responseRatenumber

Percentage (0-100) of conversations that received a client rating: rated conversations / conversationCount x 100.

averageRatingnumber

Average rating (1-5) of the rated conversations. 0 when none were rated.

csatnumber

Percentage (0-100) of rated conversations rated 4 or 5. 0 when none were rated.

createdAtDateTime

When the row was first written. startDate and endDate filter on this value.

Combining rows. Counts can be summed across rows. Averages must be weighted when you merge rows:

  • avgFirstResponseTime: weight by firstResponseConversationCount.
  • avgConversationTime: weight by conversationCount.
  • averageRating: weight by the number of rated conversations, responseRate x conversationCount / 100.
  • csat: recompute from the positive ratings, csat x rated conversations / 100, over the total rated conversations.

How message reports are built

messageReport returns one row per workspace and UTC hour. A background job runs every hour at minute 5 (UTC) and writes the hour that just closed, for every workspace with at least one active Channel. Hours with no messages get a row with zero counts. If a run is missed, hours from the last 12 hours that have no row yet are filled in on the next run. A row is not rewritten after its hour has been processed.

  • totalCount counts every message created in the hour, both from clients and from the business side. Internal notes are excluded.
  • The status counts (sentCount, deliveredCount, readCount, failedCount, pendingCount, playedCount) use each message’s latest status when the row was written. A message that was delivered and then read counts only as read. Status changes after that are not reflected.
  • Client messages have no delivery status, so they count only toward totalCount. totalCount minus the six status counts gives the number of messages without a status.

messageReportToday uses the same rules but counts live from UTC midnight, including the hour still in progress, with statuses as they are at query time. To build a daily series without counting an hour twice, use messageReport up to the end of yesterday (endDate = today’s UTC midnight minus 1 ms) and add messageReportToday for today.

Conversations Report API

Get conversation metrics broken down by Channel and by the hour of the day the conversations ended. Each node covers one Channel, one UTC day and one hour, and holds every conversation that ended in that hour. Group nodes by the UTC date of createdAt to get daily totals.

Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

Only return rows for this Channel (integration) ID. Omit it to include all Channels.

startDateDateTime

Required. Start of the range (inclusive), compared to each row's createdAt. Not rounded, so send T00:00:00.000Z to start at a UTC day boundary.

endDateDateTime

Required. End of the range (inclusive), compared to each row's createdAt. Send T23:59:59.999Z to include the whole last UTC day.

Report fields

Each node in nodes has these fields. See How conversation reports are built for how they are calculated.

FieldTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The report row ID.

integrationIdstring

The Channel (integration) ID of the conversations.

hournumber

Hour of the day (0-23, UTC) in which the conversations ended. The day is the UTC date of createdAt.

conversationCountnumber

Conversations that ended in this bucket.

agentMessagesCountnumber

Business-side messages (agents, AI assistants, automated replies) in those conversations, counted over the whole conversation. Internal notes are excluded.

clientMessageCountnumber

Messages the client sent in those conversations, counted over the whole conversation.

avgFirstResponseTimenumber

Average seconds from the client's first message to the first business-side message. Only conversations where the client wrote first are included. 0 when none qualify.

firstResponseConversationCountnumber

Conversations included in avgFirstResponseTime.

avgConversationTimenumber

Average seconds from conversation creation to conversation end.

newClientConvCountnumber

Conversations that were the client's first conversation in the workspace. Can be null.

responseRatenumber

Percentage (0-100) of conversations that received a client rating.

averageRatingnumber

Average rating (1-5) of the rated conversations. 0 when none were rated.

csatnumber

Percentage (0-100) of rated conversations rated 4 or 5. 0 when none were rated.

createdAtDateTime

When the row was first written, the end time of the first conversation in this hour.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query convsReport($input: ConvsReportInput!) { convsReport(input: $input) { nodes { id integrationId hour conversationCount agentMessagesCount clientMessageCount avgFirstResponseTime firstResponseConversationCount avgConversationTime newClientConvCount responseRate averageRating csat createdAt } } } input ConvsReportInput { workspaceId: Int! # Workspace ID. integrationId: ID # Filter by Channel (integration) ID. startDate: DateTime! # Range start (inclusive), compared to the row createdAt. endDate: DateTime! # Range end (inclusive), compared to the row createdAt. }

The query above returns JSON structured like this:

{ "data": { "convsReport": { "nodes": [ { "id": "convreport_456", "integrationId": "integration_123", "hour": 14, "conversationCount": 8, "agentMessagesCount": 46, "clientMessageCount": 39, "avgFirstResponseTime": 95, "firstResponseConversationCount": 7, "avgConversationTime": 1830, "newClientConvCount": 3, "responseRate": 50, "averageRating": 4.25, "csat": 75, "createdAt": "2026-10-17T14:03:12.000Z" }, { "id": "convreport_123", "integrationId": "integration_123", "hour": 9, "conversationCount": 5, "agentMessagesCount": 21, "clientMessageCount": 18, "avgFirstResponseTime": 140, "firstResponseConversationCount": 5, "avgConversationTime": 2400, "newClientConvCount": 1, "responseRate": 20, "averageRating": 3, "csat": 0, "createdAt": "2026-10-17T09:12:40.000Z" } ] } } }

Rows are sorted by createdAt, newest first, and are not paginated. A bucket where no conversation ended has no row. In the example, four of the eight conversations that ended between 14:00 and 15:00 were rated (responseRate 50) with 5, 5, 4 and 3 (averageRating 4.25, csat 75).

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"convsReport","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","startDate":"2026-10-17T00:00:00.000Z","endDate":"2026-10-17T23:59:59.999Z"}},"query":"query convsReport($input: ConvsReportInput!) {\n convsReport(input: $input) {\n nodes {\n id\n integrationId\n hour\n conversationCount\n agentMessagesCount\n clientMessageCount\n avgFirstResponseTime\n firstResponseConversationCount\n avgConversationTime\n newClientConvCount\n responseRate\n averageRating\n csat\n createdAt\n }\n }\n}"}'

Agents Report API

Get conversation metrics per human agent, per Channel and per UTC day. A conversation is attributed to the last human (non-AI) agent in its assignment history, or to its current assignee when the history has none. Conversations handled only by AI assistants are not counted here.

Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

agentIdstring

Only return rows for this agent ID. Ignored when agentIds has values.

agentIdsstring[]

Only return rows for any of these agent IDs. Takes precedence over agentId when non-empty.

integrationIdstring

Only return rows for this Channel (integration) ID. Omit it to include all Channels.

startDateDateTime

Required. Start of the range (inclusive), compared to each row's createdAt. Not rounded, so send T00:00:00.000Z to start at a UTC day boundary.

endDateDateTime

Required. End of the range (inclusive), compared to each row's createdAt. Send T23:59:59.999Z to include the whole last UTC day.

Report fields

Each node in nodes has these fields. See How conversation reports are built for how they are calculated.

FieldTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The report row ID.

agentIdstring

The agent the conversations are attributed to.

integrationIdstring

The Channel (integration) ID of the conversations. Can be null.

conversationCountnumber

Conversations that ended in this bucket.

agentMessagesCountnumber

Business-side messages (agents, AI assistants, automated replies) in those conversations, counted over the whole conversation. Internal notes are excluded.

clientMessageCountnumber

Messages the client sent in those conversations, counted over the whole conversation.

avgFirstResponseTimenumber

Average seconds from the client's first message to the first business-side message. Only conversations where the client wrote first are included. 0 when none qualify.

firstResponseConversationCountnumber

Conversations included in avgFirstResponseTime.

avgConversationTimenumber

Average seconds from conversation creation to conversation end.

newClientConvCountnumber

Conversations that were the client's first conversation in the workspace. Can be null.

responseRatenumber

Percentage (0-100) of conversations that received a client rating.

averageRatingnumber

Average rating (1-5) of the rated conversations. 0 when none were rated.

csatnumber

Percentage (0-100) of rated conversations rated 4 or 5. 0 when none were rated.

createdAtDateTime

When the row was first written, the end time of the agent's first conversation that day. The day of the row is the UTC date of this value.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query agentsReport($input: AgentsReportInput!) { agentsReport(input: $input) { nodes { id agentId integrationId conversationCount agentMessagesCount clientMessageCount avgFirstResponseTime firstResponseConversationCount avgConversationTime newClientConvCount responseRate averageRating csat createdAt } } } input AgentsReportInput { workspaceId: Int! # Workspace ID. agentId: ID # Filter by one agent ID. agentIds: [ID!] # Filter by any of these agent IDs. Wins over agentId when non-empty. integrationId: ID # Filter by Channel (integration) ID. startDate: DateTime! # Range start (inclusive), compared to the row createdAt. endDate: DateTime! # Range end (inclusive), compared to the row createdAt. }

The query above returns JSON structured like this:

{ "data": { "agentsReport": { "nodes": [ { "id": "agentreport_789", "agentId": "agent_123", "integrationId": "integration_123", "conversationCount": 10, "agentMessagesCount": 74, "clientMessageCount": 61, "avgFirstResponseTime": 82, "firstResponseConversationCount": 9, "avgConversationTime": 1520, "newClientConvCount": 4, "responseRate": 40, "averageRating": 4, "csat": 75, "createdAt": "2026-10-17T08:41:05.000Z" }, { "id": "agentreport_456", "agentId": "agent_456", "integrationId": "integration_123", "conversationCount": 6, "agentMessagesCount": 30, "clientMessageCount": 28, "avgFirstResponseTime": 210, "firstResponseConversationCount": 6, "avgConversationTime": 2950, "newClientConvCount": 2, "responseRate": 0, "averageRating": 0, "csat": 0, "createdAt": "2026-10-16T10:15:30.000Z" } ] } } }

Rows are sorted by createdAt, newest first, and are not paginated. A bucket where no conversation ended has no row.

agentMessagesCount counts all business-side messages in the attributed conversations, including messages from other agents or AI assistants in the same conversation, not only the messages this agent sent.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"agentsReport","variables":{"input":{"workspaceId":12,"agentIds":["agent_123","agent_456"],"startDate":"2026-10-16T00:00:00.000Z","endDate":"2026-10-17T23:59:59.999Z"}},"query":"query agentsReport($input: AgentsReportInput!) {\n agentsReport(input: $input) {\n nodes {\n id\n agentId\n integrationId\n conversationCount\n agentMessagesCount\n clientMessageCount\n avgFirstResponseTime\n firstResponseConversationCount\n avgConversationTime\n newClientConvCount\n responseRate\n averageRating\n csat\n createdAt\n }\n }\n}"}'

Conversation Stages Report API

Get conversation metrics per lifecycle stage, per Channel and per UTC day. A conversation counts toward the stage it has when it ends. Conversations without a lifecycle stage are not counted.

Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

Only return rows for this Channel (integration) ID. Omit it to include all Channels.

stagestring

Only return rows for this lifecycle stage name (exact match). Ignored when stages has values.

stagesstring[]

Only return rows for any of these lifecycle stage names. Takes precedence over stage when non-empty.

startDateDateTime

Required. Start of the range (inclusive), compared to each row's createdAt. Not rounded, so send T00:00:00.000Z to start at a UTC day boundary.

endDateDateTime

Required. End of the range (inclusive), compared to each row's createdAt. Send T23:59:59.999Z to include the whole last UTC day.

Report fields

Each node in nodes has these fields. See How conversation reports are built for how they are calculated.

FieldTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The report row ID.

stagestring

The lifecycle stage name.

integrationIdstring

The Channel (integration) ID of the conversations.

conversationCountnumber

Conversations that ended in this bucket.

agentMessagesCountnumber

Business-side messages (agents, AI assistants, automated replies) in those conversations, counted over the whole conversation. Internal notes are excluded.

clientMessageCountnumber

Messages the client sent in those conversations, counted over the whole conversation.

avgFirstResponseTimenumber

Average seconds from the client's first message to the first business-side message. Only conversations where the client wrote first are included. 0 when none qualify.

firstResponseConversationCountnumber

Conversations included in avgFirstResponseTime.

avgConversationTimenumber

Average seconds from conversation creation to conversation end.

newClientConvCountnumber

Conversations that were the client's first conversation in the workspace. Can be null.

responseRatenumber

Percentage (0-100) of conversations that received a client rating.

averageRatingnumber

Average rating (1-5) of the rated conversations. 0 when none were rated.

csatnumber

Percentage (0-100) of rated conversations rated 4 or 5. 0 when none were rated.

createdAtDateTime

When the row was first written, the end time of the first conversation in this stage that day. The day of the row is the UTC date of this value.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query convStagesReport($input: ConvStagesReportInput!) { convStagesReport(input: $input) { nodes { id stage integrationId conversationCount agentMessagesCount clientMessageCount avgFirstResponseTime firstResponseConversationCount avgConversationTime newClientConvCount responseRate averageRating csat createdAt } } } input ConvStagesReportInput { workspaceId: Int! # Workspace ID. integrationId: ID # Filter by Channel (integration) ID. stage: String # Filter by one lifecycle stage name. stages: [String!] # Filter by any of these stage names. Wins over stage when non-empty. startDate: DateTime! # Range start (inclusive), compared to the row createdAt. endDate: DateTime! # Range end (inclusive), compared to the row createdAt. }

The query above returns JSON structured like this:

{ "data": { "convStagesReport": { "nodes": [ { "id": "stagereport_456", "stage": "Won", "integrationId": "integration_123", "conversationCount": 4, "agentMessagesCount": 22, "clientMessageCount": 19, "avgFirstResponseTime": 60, "firstResponseConversationCount": 4, "avgConversationTime": 3600, "newClientConvCount": 1, "responseRate": 50, "averageRating": 4.5, "csat": 100, "createdAt": "2026-10-17T11:20:00.000Z" }, { "id": "stagereport_123", "stage": "Qualified", "integrationId": "integration_123", "conversationCount": 7, "agentMessagesCount": 35, "clientMessageCount": 33, "avgFirstResponseTime": 120, "firstResponseConversationCount": 6, "avgConversationTime": 2700, "newClientConvCount": 5, "responseRate": 0, "averageRating": 0, "csat": 0, "createdAt": "2026-10-17T08:05:45.000Z" } ] } } }

Rows are sorted by createdAt, newest first, and are not paginated. A bucket where no conversation ended has no row. Moving a conversation to another stage after it ended doesn’t change rows that were already written.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"convStagesReport","variables":{"input":{"workspaceId":12,"stages":["Qualified","Won"],"startDate":"2026-10-17T00:00:00.000Z","endDate":"2026-10-17T23:59:59.999Z"}},"query":"query convStagesReport($input: ConvStagesReportInput!) {\n convStagesReport(input: $input) {\n nodes {\n id\n stage\n integrationId\n conversationCount\n agentMessagesCount\n clientMessageCount\n avgFirstResponseTime\n firstResponseConversationCount\n avgConversationTime\n newClientConvCount\n responseRate\n averageRating\n csat\n createdAt\n }\n }\n}"}'

Conversation Tags Report API

Get conversation metrics per conversation tag, per Channel and per UTC day. When a conversation ends, it counts once toward each tag it has, so the same conversation can appear in several rows. Conversations without tags are not counted.

Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

Only return rows for this Channel (integration) ID. Omit it to include all Channels.

tagstring

Only return rows for this tag name (exact match). Ignored when tags has values.

tagsstring[]

Only return rows for any of these tag names. Takes precedence over tag when non-empty.

startDateDateTime

Required. Start of the range (inclusive), compared to each row's createdAt. Not rounded, so send T00:00:00.000Z to start at a UTC day boundary.

endDateDateTime

Required. End of the range (inclusive), compared to each row's createdAt. Send T23:59:59.999Z to include the whole last UTC day.

Report fields

Each node in nodes has these fields. See How conversation reports are built for how they are calculated.

FieldTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The report row ID.

tagstring

The tag name.

integrationIdstring

The Channel (integration) ID of the conversations.

conversationCountnumber

Conversations that ended in this bucket.

agentMessagesCountnumber

Business-side messages (agents, AI assistants, automated replies) in those conversations, counted over the whole conversation. Internal notes are excluded.

clientMessageCountnumber

Messages the client sent in those conversations, counted over the whole conversation.

avgFirstResponseTimenumber

Average seconds from the client's first message to the first business-side message. Only conversations where the client wrote first are included. 0 when none qualify.

firstResponseConversationCountnumber

Conversations included in avgFirstResponseTime.

avgConversationTimenumber

Average seconds from conversation creation to conversation end.

newClientConvCountnumber

Conversations that were the client's first conversation in the workspace. Can be null.

responseRatenumber

Percentage (0-100) of conversations that received a client rating.

averageRatingnumber

Average rating (1-5) of the rated conversations. 0 when none were rated.

csatnumber

Percentage (0-100) of rated conversations rated 4 or 5. 0 when none were rated.

createdAtDateTime

When the row was first written, the end time of the first conversation with this tag that day. The day of the row is the UTC date of this value.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query convTagsReport($input: ConvTagsReportInput!) { convTagsReport(input: $input) { nodes { id tag integrationId conversationCount agentMessagesCount clientMessageCount avgFirstResponseTime firstResponseConversationCount avgConversationTime newClientConvCount responseRate averageRating csat createdAt } } } input ConvTagsReportInput { workspaceId: Int! # Workspace ID. integrationId: ID # Filter by Channel (integration) ID. tag: String # Filter by one tag name. tags: [String!] # Filter by any of these tag names. Wins over tag when non-empty. startDate: DateTime! # Range start (inclusive), compared to the row createdAt. endDate: DateTime! # Range end (inclusive), compared to the row createdAt. }

The query above returns JSON structured like this:

{ "data": { "convTagsReport": { "nodes": [ { "id": "tagreport_456", "tag": "refund", "integrationId": "integration_123", "conversationCount": 4, "agentMessagesCount": 18, "clientMessageCount": 20, "avgFirstResponseTime": 150, "firstResponseConversationCount": 4, "avgConversationTime": 2100, "newClientConvCount": 0, "responseRate": 25, "averageRating": 2, "csat": 0, "createdAt": "2026-10-17T12:47:10.000Z" }, { "id": "tagreport_123", "tag": "billing", "integrationId": "integration_123", "conversationCount": 8, "agentMessagesCount": 40, "clientMessageCount": 37, "avgFirstResponseTime": 75, "firstResponseConversationCount": 8, "avgConversationTime": 1980, "newClientConvCount": 2, "responseRate": 50, "averageRating": 4, "csat": 75, "createdAt": "2026-10-17T09:02:33.000Z" } ] } } }

Rows are sorted by createdAt, newest first, and are not paginated. A bucket where no conversation ended has no row. Because a conversation counts toward every tag it has, adding up conversationCount across tags can be higher than the number of conversations that ended.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"convTagsReport","variables":{"input":{"workspaceId":12,"tags":["billing","refund"],"startDate":"2026-10-17T00:00:00.000Z","endDate":"2026-10-17T23:59:59.999Z"}},"query":"query convTagsReport($input: ConvTagsReportInput!) {\n convTagsReport(input: $input) {\n nodes {\n id\n tag\n integrationId\n conversationCount\n agentMessagesCount\n clientMessageCount\n avgFirstResponseTime\n firstResponseConversationCount\n avgConversationTime\n newClientConvCount\n responseRate\n averageRating\n csat\n createdAt\n }\n }\n}"}'

Hourly Message Report API

Get message counts per UTC hour for a workspace. Each node covers one hour, starting at reportHour. Rows are written by an hourly job, so the hour in progress and the hour that closed less than about 5 minutes ago are not included yet. Use Today’s Message Report API for live numbers.

Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

startDateDateTime

Required. Start of the range (inclusive). Rounded down to the start of its UTC hour.

endDateDateTime

Required. End of the range (inclusive). Rounded down to the start of its UTC hour, and that hour is included.

Report fields

Each node in nodes has these fields. See How message reports are built.

FieldTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The report row ID.

reportHourDateTime

UTC start of the hour this row covers. The row counts messages created from reportHour up to, but not including, the next hour.

totalCountnumber

All messages created in the hour, from clients and from the business side. Internal notes are excluded.

sentCountnumber

Messages whose status was sent when the row was written.

deliveredCountnumber

Messages whose status was delivered when the row was written.

readCountnumber

Messages whose status was read when the row was written.

failedCountnumber

Messages whose status was failed when the row was written.

pendingCountnumber

Messages whose status was pending when the row was written.

playedCountnumber

Messages whose status was played when the row was written.

createdAtDateTime

When the row was first written, usually about 5 minutes after the hour closed.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query messageReport($input: MessageReportInput!) { messageReport(input: $input) { nodes { id reportHour totalCount sentCount deliveredCount readCount failedCount pendingCount playedCount createdAt } } } input MessageReportInput { workspaceId: Int! # Workspace ID. startDate: DateTime! # Range start (inclusive), rounded down to the UTC hour. endDate: DateTime! # Range end (inclusive), rounded down to the UTC hour. }

The query above returns JSON structured like this:

{ "data": { "messageReport": { "nodes": [ { "id": "messagereport_456", "reportHour": "2026-10-16T23:00:00.000Z", "totalCount": 42, "sentCount": 3, "deliveredCount": 10, "readCount": 12, "failedCount": 1, "pendingCount": 0, "playedCount": 1, "createdAt": "2026-10-17T00:05:03.000Z" }, { "id": "messagereport_123", "reportHour": "2026-10-16T22:00:00.000Z", "totalCount": 0, "sentCount": 0, "deliveredCount": 0, "readCount": 0, "failedCount": 0, "pendingCount": 0, "playedCount": 0, "createdAt": "2026-10-16T23:05:02.000Z" } ] } } }

Rows are sorted by reportHour, newest first, and are not paginated. The example range returns up to 24 rows, from 00:00 to 23:00 UTC; two are shown. In the 23:00 row, 27 messages have a status and the other 15 are client messages, which have no delivery status.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"messageReport","variables":{"input":{"workspaceId":12,"startDate":"2026-10-16T00:00:00.000Z","endDate":"2026-10-16T23:59:59.999Z"}},"query":"query messageReport($input: MessageReportInput!) {\n messageReport(input: $input) {\n nodes {\n id\n reportHour\n totalCount\n sentCount\n deliveredCount\n readCount\n failedCount\n pendingCount\n playedCount\n createdAt\n }\n }\n}"}'

Today’s Message Report API

Get live message counts for the current UTC day, from 00:00 UTC up to now, including the hour still in progress. Counts are computed at query time, so statuses are current.

Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

Report fields

FieldTypeDescription
workspaceIdnumber

The workspace ID.

reportDateDateTime

UTC midnight that starts the current day.

totalCountnumber

All messages created today, from clients and from the business side. Internal notes are excluded.

sentCountnumber

Messages whose current status is sent.

deliveredCountnumber

Messages whose current status is delivered.

readCountnumber

Messages whose current status is read.

failedCountnumber

Messages whose current status is failed.

pendingCountnumber

Messages whose current status is pending.

playedCountnumber

Messages whose current status is played.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query messageReportToday($input: MessageReportTodayInput!) { messageReportToday(input: $input) { workspaceId reportDate totalCount sentCount deliveredCount readCount failedCount pendingCount playedCount } } input MessageReportTodayInput { workspaceId: Int! # Workspace ID. }

The query above returns JSON structured like this:

{ "data": { "messageReportToday": { "workspaceId": 12, "reportDate": "2026-10-17T00:00:00.000Z", "totalCount": 318, "sentCount": 12, "deliveredCount": 64, "readCount": 88, "failedCount": 4, "pendingCount": 2, "playedCount": 3 } } }

Client messages have no delivery status, so they count only toward totalCount. In the example, 173 messages have a status and 145 are client messages. To chart the last few days without counting an hour twice, combine this result with the Hourly Message Report API up to the end of yesterday.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"messageReportToday","variables":{"input":{"workspaceId":12}},"query":"query messageReportToday($input: MessageReportTodayInput!) {\n messageReportToday(input: $input) {\n workspaceId\n reportDate\n totalCount\n sentCount\n deliveredCount\n readCount\n failedCount\n pendingCount\n playedCount\n }\n}"}'