API Reference
Project Statistics
/cs/v1/content_creation/statistics/projectUsage and cost for a single project, bucketed by day or by calendar month over the date range you ask for.
Figures are recomputed every hour, at half past (UTC), from your answers and billing events. The previous day is recomputed at 00:00 UTC, and the last three complete days are recomputed at 06:00 UTC. The current day therefore stays partial until it ends (UTC) and may still move slightly afterwards. The engage*Count fields come from a daily rollup instead: they cover complete days only, so the current day and the day before can read 0 until it has run.
startDate and endDate are both inclusive, and days are counted in UTC — a range of 2026-07-01 to 2026-07-31 covers the whole of July.
Open interactive API explorer ↗ · Download OpenAPI
Authentication
bearerAuth
Bearer authentication header of the form Bearer <token>, where <token> is an access key.
Example: Authorization: Bearer sk-proj-XXXXXXXXX
Type: bearer
Parameters
projectGid query · stringrequiredThe project to report on. When you authenticate with an access key, this must be the project that key belongs to.
Type:stringstartDate query · stringrequiredFirst day to include, as YYYY-MM-DD (UTC). Inclusive.
stringendDate query · stringrequiredLast day to include, as YYYY-MM-DD (UTC). Inclusive.
stringgroupBy query · stringSize of each bucket in rows: one row per day, or one row per calendar month.
stringdefault: "DAILY"Allowed values: "DAILY", "MONTHLY"
Responses
#200 Response
OK
#*/*
Usage and cost for a project over the requested range, split into buckets plus a grand total.
Every amount is in your account currency, as a decimal string so no precision is lost when you parse it.
Type:object#rows arrayrequired
One entry per bucket that recorded activity, most recent first. Buckets with no activity at all are omitted.
Type:array#Array items
Usage and cost recorded for one bucket of the requested range.
Type:objectdate stringrequiredThe bucket, as YYYY-MM-DD. With groupBy=MONTHLY this is the first day of that month.
string#metrics objectrequired
What the project used and what it cost, over one bucket or over the whole requested range.
Counts are integers. Amounts are in your account currency, as plain decimal strings (21.25, 0.0) so no precision is lost when you parse them.
objectanswerMessageCount integerrequiredHow many of your users' messages the answers of this bucket replied to.
Type:integerformat: "int64"answerHumanCount integerrequiredAnswers written by a human operator, in HUMAN reply mode. Human operators were retired on 2026-10-19: only earlier buckets can hold a value.
integerformat: "int64"answerHumanCost stringrequiredWhat those human-written answers cost you. Zero after 2026-10-19.
Type:stringanswerAiCount integerrequiredAnswers generated by the model, in AI reply mode.
integerformat: "int64"messageDroppedCount integerrequiredGeneration requests that ended without a reply: a guardrail stopped the conversation with its answer option off, or the request's maxProcessingTimeSeconds limit, where it applies, ran out before a reply came (a long wait, a conversation already stopped, a missing profile, or a failed generation). Each one sends a conversation.dropped event to a project subscribed to it. Not billed.
integerformat: "int64"answerActionCount integerrequiredAnswers carrying an action rather than a text reply (ACTION_* types: pokes, picture requests, profile reports, …).
integerformat: "int64"cost stringrequiredEverything billed on the answers of this bucket — AI and human replies, plus any Smart Fetch performed while writing them. This is the figure to use for a project's answer spend.
Media analyses and suggestion requests are billed outside of answers, so they are not part of this amount. They appear here as counts (photoAnalysisCount, videoAnalysisCount, audioAnalysisCount, icebreakerSuggestionCount, followupSuggestionCount) — multiply them by your per-unit price to get their spend.
stringanswerFreeCount integerrequiredAnswers that were not billed — mostly the follow-up messages of a multi-message reply, which is billed once on the first answer.
Type:integerformat: "int64"photoAnalysisCount integerrequiredPhoto Analyses run on pictures your users sent. Billed outside of answers — see cost.
integerformat: "int64"audioAnalysisCount integerrequiredVoice-message analyses billed, counted in 30-second slices: a voice message sent by a user and transcribed so the persona could reply to what was actually said counts once per 30 seconds started, so one to three times up to the 90-second limit. A recording carrying no signal at all (a muted or unplugged mic), longer than 90 seconds, or whose length could not be measured is not analysed and not counted here.
Type:integerformat: "int64"webSearchCount integerrequiredSmart Fetch lookups performed while writing answers.
Type:integerformat: "int64"webSearchCost stringrequiredWhat those Smart Fetch lookups cost you. Already included in cost.
stringicebreakerSuggestionCount integerrequiredIcebreaker suggestions requested from the suggestions endpoint — a suggestion call on a conversation with no history. Billed outside of answers. Icebreaker replies generated in a conversation through engage are engageIcebreakerCount.
integerformat: "int64"followupSuggestionCount integerrequiredFollow-up suggestions requested from the suggestions endpoint — a suggestion call on a conversation that already has messages. Billed outside of answers. Engage replies generated in a conversation are the engage*Count fields.
integerformat: "int64"engageIcebreakerCount integerrequiredIcebreaker replies generated for an ICEBREAKER engage action. Already counted and billed in answerAiCount and cost, so it has no cost of its own. A request sent with AUTO counts as the action it resolved to. Counted from 2026-09-08, for complete UTC days only: the current day and the day before can still read 0 until the daily rollup has run.
integerformat: "int64"engageNudgeCount integerrequiredReplies generated for a NUDGE engage action. Already counted and billed in answerAiCount and cost, so it has no cost of its own. A request sent with AUTO counts as the action it resolved to. Counted from 2026-09-08, for complete UTC days only: the current day and the day before can still read 0 until the daily rollup has run.
integerformat: "int64"engageReviveCount integerrequiredReplies generated for a REVIVE engage action. Already counted and billed in answerAiCount and cost, so it has no cost of its own. A request sent with AUTO counts as the action it resolved to. Counted from 2026-09-08, for complete UTC days only: the current day and the day before can still read 0 until the daily rollup has run.
integerformat: "int64"engageLateReplyCount integerrequiredReplies generated for a LATE_REPLY engage action. Already counted and billed in answerAiCount and cost, so it has no cost of its own. A request sent with AUTO counts as the action it resolved to. Counted from 2026-09-08, for complete UTC days only: the current day and the day before can still read 0 until the daily rollup has run.
integerformat: "int64"engageChangeTopicCount integerrequiredReplies generated with the change-topic arc of a CHANGE_TOPIC engage action; a request that fell back to an icebreaker or an ordinary reply is not counted. Already counted and billed in answerAiCount and cost, so it has no cost of its own. A request sent with AUTO counts as the action it resolved to. Counted from 2026-09-08, for complete UTC days only: the current day and the day before can still read 0 until the daily rollup has run.
integerformat: "int64"#total objectrequired
The same metrics summed over every returned bucket, so you don't have to add up rows yourself.
objectanswerMessageCount integerrequiredHow many of your users' messages the answers of this bucket replied to.
Type:integerformat: "int64"answerHumanCount integerrequiredAnswers written by a human operator, in HUMAN reply mode. Human operators were retired on 2026-10-19: only earlier buckets can hold a value.
integerformat: "int64"answerHumanCost stringrequiredWhat those human-written answers cost you. Zero after 2026-10-19.
Type:stringanswerAiCount integerrequiredAnswers generated by the model, in AI reply mode.
integerformat: "int64"messageDroppedCount integerrequiredGeneration requests that ended without a reply: a guardrail stopped the conversation with its answer option off, or the request's maxProcessingTimeSeconds limit, where it applies, ran out before a reply came (a long wait, a conversation already stopped, a missing profile, or a failed generation). Each one sends a conversation.dropped event to a project subscribed to it. Not billed.
integerformat: "int64"answerActionCount integerrequiredAnswers carrying an action rather than a text reply (ACTION_* types: pokes, picture requests, profile reports, …).
integerformat: "int64"cost stringrequiredEverything billed on the answers of this bucket — AI and human replies, plus any Smart Fetch performed while writing them. This is the figure to use for a project's answer spend.
Media analyses and suggestion requests are billed outside of answers, so they are not part of this amount. They appear here as counts (photoAnalysisCount, videoAnalysisCount, audioAnalysisCount, icebreakerSuggestionCount, followupSuggestionCount) — multiply them by your per-unit price to get their spend.
stringanswerFreeCount integerrequiredAnswers that were not billed — mostly the follow-up messages of a multi-message reply, which is billed once on the first answer.
Type:integerformat: "int64"photoAnalysisCount integerrequiredPhoto Analyses run on pictures your users sent. Billed outside of answers — see cost.
integerformat: "int64"audioAnalysisCount integerrequiredVoice-message analyses billed, counted in 30-second slices: a voice message sent by a user and transcribed so the persona could reply to what was actually said counts once per 30 seconds started, so one to three times up to the 90-second limit. A recording carrying no signal at all (a muted or unplugged mic), longer than 90 seconds, or whose length could not be measured is not analysed and not counted here.
Type:integerformat: "int64"webSearchCount integerrequiredSmart Fetch lookups performed while writing answers.
Type:integerformat: "int64"webSearchCost stringrequiredWhat those Smart Fetch lookups cost you. Already included in cost.
stringicebreakerSuggestionCount integerrequiredIcebreaker suggestions requested from the suggestions endpoint — a suggestion call on a conversation with no history. Billed outside of answers. Icebreaker replies generated in a conversation through engage are engageIcebreakerCount.
integerformat: "int64"followupSuggestionCount integerrequiredFollow-up suggestions requested from the suggestions endpoint — a suggestion call on a conversation that already has messages. Billed outside of answers. Engage replies generated in a conversation are the engage*Count fields.
integerformat: "int64"engageIcebreakerCount integerrequiredIcebreaker replies generated for an ICEBREAKER engage action. Already counted and billed in answerAiCount and cost, so it has no cost of its own. A request sent with AUTO counts as the action it resolved to. Counted from 2026-09-08, for complete UTC days only: the current day and the day before can still read 0 until the daily rollup has run.
integerformat: "int64"engageNudgeCount integerrequiredReplies generated for a NUDGE engage action. Already counted and billed in answerAiCount and cost, so it has no cost of its own. A request sent with AUTO counts as the action it resolved to. Counted from 2026-09-08, for complete UTC days only: the current day and the day before can still read 0 until the daily rollup has run.
integerformat: "int64"engageReviveCount integerrequiredReplies generated for a REVIVE engage action. Already counted and billed in answerAiCount and cost, so it has no cost of its own. A request sent with AUTO counts as the action it resolved to. Counted from 2026-09-08, for complete UTC days only: the current day and the day before can still read 0 until the daily rollup has run.
integerformat: "int64"engageLateReplyCount integerrequiredReplies generated for a LATE_REPLY engage action. Already counted and billed in answerAiCount and cost, so it has no cost of its own. A request sent with AUTO counts as the action it resolved to. Counted from 2026-09-08, for complete UTC days only: the current day and the day before can still read 0 until the daily rollup has run.
integerformat: "int64"engageChangeTopicCount integerrequiredReplies generated with the change-topic arc of a CHANGE_TOPIC engage action; a request that fell back to an icebreaker or an ordinary reply is not counted. Already counted and billed in answerAiCount and cost, so it has no cost of its own. A request sent with AUTO counts as the action it resolved to. Counted from 2026-09-08, for complete UTC days only: the current day and the day before can still read 0 until the daily rollup has run.
integerformat: "int64"Illustrative example
{
"rows": [
{
"date": "2026-07-14",
"metrics": {
"answerMessageCount": "1420",
"answerHumanCount": "12",
"answerHumanCost": "0.3",
"answerAiCount": "838",
"answerAiCost": "20.95",
"messageDroppedCount": "7",
"answerActionCount": "23",
"cost": "21.25",
"answerFreeCount": "134",
"photoAnalysisCount": "58",
"photoAnalysisCost": 0,
"videoAnalysisCount": 0,
"videoAnalysisCost": 0,
"audioAnalysisCount": "24",
"audioAnalysisCost": 0,
"webSearchCount": "16",
"webSearchCost": "0.8",
"icebreakerSuggestionCount": "31",
"followupSuggestionCount": "44",
"engageIcebreakerCount": "212",
"engageNudgeCount": "2740",
"engageReviveCount": "17",
"engageLateReplyCount": "36",
"engageChangeTopicCount": "4"
}
}
],
"total": {
"answerMessageCount": "1420",
"answerHumanCount": "12",
"answerHumanCost": "0.3",
"answerAiCount": "838",
"answerAiCost": "20.95",
"messageDroppedCount": "7",
"answerActionCount": "23",
"cost": "21.25",
"answerFreeCount": "134",
"photoAnalysisCount": "58",
"photoAnalysisCost": 0,
"videoAnalysisCount": 0,
"videoAnalysisCost": 0,
"audioAnalysisCount": "24",
"audioAnalysisCost": 0,
"webSearchCount": "16",
"webSearchCost": "0.8",
"icebreakerSuggestionCount": "31",
"followupSuggestionCount": "44",
"engageIcebreakerCount": "212",
"engageNudgeCount": "2740",
"engageReviveCount": "17",
"engageLateReplyCount": "36",
"engageChangeTopicCount": "4"
}
}