Plan and usage API
Your plan and usage, what the next plan gives, and what was used and charged between two dates.
Endpoints
/api/v1/account/getPlanAndUsageRead this workspace's plan and usage in one answer: the plan and its monthly price, the balance and whether extra usage is on, when the plan renews, and for every meter the plan limits (AI credits and each meter of the Usage screen) what is used against its limit, when it starts again and the exact words a person reads at that limit. Use it to answer "how much have we used", "what is left this month", "what happens when we run out" or "what does the next plan cost and give". No params. Returns { plan: { name, priceCents, isFree }, renewsOn (ISO; null on Free or when the plan is set to end), balanceVisible, balanceCents, allowExtraUsage, meters: [{ key, label, unit, used, limit, resetsOn, atLimit }], nextPlan }. In meters: limit null = no limit on this plan; used null = not measured yet; resetsOn null = held, never reset; atLimit = { meter, cure, message } (the words at that limit for this person, and what gets the workspace going again: allowExtraUsage, addBalance, upgradePlan, waitForReset or buyAddOn), null when there is no limit. nextPlan = the next plan up, exactly as the pricing page shows it: { name, priceCents (monthly), yearlyPriceCents (null = no yearly price), monthlyCredits (AI credits a month), members (included), buildsOn (the plan it adds to), includes (what it gives, the pricing page's own lines), subscribePath (the path on the Serenities site to subscribe to it: someone on no paid plan reaches the checkout there, someone already on a paid plan is sent on to their Plan screen to change plan; null when this person may not buy it: the person who pays for this workspace can) }; null when no plan on sale costs more than this one (the top plan, or a plan priced above every plan on sale). Give its price and lines as they are; never quote a plan or price that is not in it. Who may read it: every member of the workspace (the dashboard shows them the same); payment details — the balance and the extra-usage switch — only to a person who may see them (billing.paymentDetails), others read balanceVisible false, balanceCents 0, allowExtraUsage false, and on a meter the plan sells extra of their cure is allowExtraUsage whatever the switch is, with words that ask for extra usage to be turned on or money added to the balance (true either way). From the dashboard, their AI chat, their AI client or an API key, and an agent run a person started, as that person; functions, flows, runs nobody started and agents trusted to run with their own full abilities are refused (relay the refusal as it is: it says whom to ask). Only reads: it buys, tops up or changes nothing.
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/account/getPlanAndUsage \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{}'/api/v1/account/getSpendReportRead what this workspace used, and what was charged for it, between two dates. Use it to answer "what did we spend between these dates", "how many AI credits did we use last week" or "what was charged for function calls in March". Params: from and to, each a UTC day written YYYY-MM-DD, both days included; from must be on or before to, to can be today but not in the future, and the range is at most 366 days. Returns { from, to, moneyVisible, ai: { credits, requests, inputTokens, outputTokens, cachedTokens }, aiByDay: [{ day, credits, requests }], aiCountedSince, periods: [{ meter, label, unit, start, end, used, chargedCents }] }. AI credits, requests and tokens are by exact day: ai sums the days from..to, and aiByDay lists each day that had a request or a credit. Every other meter is counted per its own period, so periods has one row per period that overlaps the range and had something used: a calendar month for function calls, run time (compute, GB-hours), bandwidth (GB), inbound emails, and the reads and writes of site tables (meters dbReads and dbWrites); a billing cycle for flow runs and for AI credits (used = the whole cycle's credits, chargedCents = what the balance paid past the plan's credits). Each row's start and end are that whole period's own first and last day, not cut to the range: say so when a period runs past the dates asked. A billing cycle that starts part-way through a UTC day counts that whole first day, and a cycle keeps the dates it was counted under even after the billing day moved. aiCountedSince is the first day from which the AI numbers are complete (daily counting began then); days before it may be missing, so say the AI figures start that day; null means daily counting has not started for this workspace yet. unit is count, gb, gb_hr or credits. chargedCents is the cents taken from the balance for that period (0 = nothing charged), or null when this person may not see payment details (moneyVisible false; the person who pays for this workspace can; they still read the same usage) or when an older period's charge was not recorded per period. The plan's own price is not here: account_getPlanAndUsage has it. Who may read it: every member of the workspace, from the dashboard, their AI chat, their AI client or an API key, and an agent run a person started, as that person; functions, flows, runs nobody started and agents trusted to run with their own full abilities are refused (relay the refusal as it is), at most 30 calls a minute per person. Only reads: it buys or changes nothing.
Parameters
from | stringrequired | |
to | stringrequired |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/account/getSpendReport \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"from": "example",
"to": "example"
}'