Stats
GET /v1/stats
Requires the stats:read scope. Takes no parameters.
The smallest endpoint on the surface, and the one a scheduled job reaches for first: a nightly check asking how much of the plan is left should not have to page the entire share list to count.
Request
curl https://api.credenshare.io/v1/stats \
-H "Authorization: Bearer crs_sk_live_<keyId>.<authSecret>"
Success response
200 OK:
{
"shares": {
"active": 12,
"expired": 47,
"total_viewed": 156
},
"daily_views": [
{ "date": "2026-08-21", "count": 3 },
{ "date": "2026-08-22", "count": 0 },
{ "date": "2026-09-03", "count": 11 }
]
}
| Field | Meaning |
|---|---|
shares.active | Shares that have not expired. |
shares.expired | Shares that have. |
shares.total_viewed | Total view events across the account, not a count of distinct shares. |
daily_views | A contiguous 14-day window, oldest first. |
daily_views is always 14 entries
The window is fixed at 14 days, zero-filled, in UTC. date is YYYY-MM-DD; a day with no activity is present with count: 0 rather than absent, so you never have to gap-fill.
daily_views is also always present, even when every count is zero. A caller that has to distinguish no data from field absent will get it wrong, so the distinction is not offered.
The window is not configurable. There is no from, to or days parameter — if you need a longer history, record these figures yourself on a schedule.
What this endpoint deliberately omits
The app's own statistics carry an organizations block with per-member figures. It is dropped here on purpose: a key scoped to stats:read must not become a way to enumerate colleagues. daily_views is kept because it is the automation-useful part and reveals nothing about identity.
There is no per-share breakdown either. If you need one, list the shares — but note that share reads are metadata only, so view counts per share are not available through the API at all.
Team accounts
When the key acts inside an organization, the figures are the organization's, not the individual member's.
That is the right answer rather than a quirk. A seat member has no meaningful figures of their own — no subscription, no plan allowance — so judging them individually yields zeros. What their automation is asking about is the team's usage. If you are reconciling against a plan allowance, this is the number that corresponds to it.
A key on a personal account gets that account's figures.
Errors
| Status | error_code | When |
|---|---|---|
| 403 | 78 | The key lacks stats:read. |
| 429 | 107 | Rate limit exceeded. Retry-After gives the seconds to wait. |
This endpoint has no path parameters and no body, so there is nothing here to fail validation. It does not 404: an account with no shares at all returns zeros, not a not-found.
The same figures over MCP
The share_stats tool returns this data as prose for a model rather than as JSON. Same figures, same 14-day window, same omissions. See MCP server.