Client API: Usage and budgets

What your services used and cost: a month by service and day, hourly rows, credit activity, budgets, billing events and questions about a charge.

Base URL: https://api.coritan.com/api/v1. Paths below are complete.

To try these requests in the browser, open the interactive Client API reference.

GET /api/v1/billing/budgets

The monthly budgets you set: one across everything the account uses (the account budget) and one for each deployment, with what counts against each this month.

A budget sends an email at 80% and at 100% (thresholds). At 100% its policy applies: block holds back previews, bursts, builds and use past a free amount, and pause stops every instance until the budget is raised or the month turns. The account budget counts every service billed by use, a virtual machine's included, and its policy applies to all of them. A deployment budget covers web services, static sites, game servers and databases, which are all deployments. A virtual machine has no deployment of its own, so only the account budget covers it. Object Storage has its own budget, set under /billing/object-storage/{id}/budget.

available lists the deployments billed by use that have no budget yet, for a form that adds one. This is the platform account's own budget; an organization's owner sets its usage budget under /api/v1/orgs/{org_slug}/billing/usage-cost.

Authentication: an access token, sent as Authorization: Bearer <token>.

Fields of a 200 response:

PUT /api/v1/billing/budgets

Set a monthly budget, or change it: the account's (scope account) or one deployment's (scope deployment with its deployment_uuid). Setting a budget above what is spent lifts what it held.

Answers 404 for a deployment this account does not pay for, 409 for one billed by its own service's plan, which a budget would never apply to, 422 for an amount that is not more than 0 and at most 1000000 with two decimal places, for a scope or policy this list does not name and for a deployment budget with no deployment_uuid, and 429 after 30 changes in an hour. Every change is in the account's activity log.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

Fields of a 200 response:

DELETE /api/v1/billing/budgets

Remove a budget and lift what it held. Answers 204 whether or not there was one, 404 for a deployment this account does not pay for, 422 for a deployment budget with no deployment_uuid and 429 after 30 changes in an hour.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/billing/charge-queries

Ask support about a charge. Name the service, the meter and the hour, and say what looks wrong. We find that hour's usage row, open a support conversation that names it (the service, meter, hour, quantity and amount) and answer with the conversation's id. Support sees the row with your message.

The hour is read in UTC and rounded down to the hour. Answers 404 when this account has no usage for that service, meter and hour, 422 for a meter this list does not name or a blank message, and 429 after 10 questions in an hour. The question is in the account's activity log.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

Fields of a 201 response:

GET /api/v1/billing/compute-usage

What the account's compute used and cost in a month, by product group.

The three groups are App Deployment (app_deployment), Cloud Compute (cloud_compute) and Container Apps (container_apps: game servers and databases), each with the number of its services billed by use, what it totals so far and a meters list: the quantity in the meter's unit, what the month's included amounts covered (included), what was billable, its amount and its forecast to the end of the month. Only services billed by use count, so a free server and a service that keeps a flat price are not in it.

pools shows the included amounts against use: the web pool is every account's and covers App Deployment, the server pool covers Cloud Compute and Container Apps together and is active only with the Paid plan (paid_plan). Each of its amounts has the used quantity, the included quantity and the share of it used (null when nothing is included, and above 1 once use passes it). The web pool's three data out meters share one amount, egress_gb.

forecast is the month's cost if each running service keeps the pace it has used the meters at (a service needs a day of use first), after the pool's included amounts. forecast_basis is pace for this month, final for an earlier one, whose forecast is its cost, and none in the first hours of a month, when every forecast is null. through is the hour the figures are settled to. spend_limit is the account's own monthly limit with what counts against it, or null.

Answers 422 for a month that is not YYYY-MM.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/billing/credit/forecast

How long the credit lasts at the pace of the last 7 days of hourly use: the daily rate, the days left and the date it runs out. Hourly use is what rated usage and flat hourly charges took from credit; renewals and one-off payments do not count.

daily_rate, days_left and runs_out_on are null when there was no hourly use in those days, and for an account that pays by invoice, which credit never runs out for (pays_by_invoice). A service stops when credit cannot pay for its hours, and a top-up starts the hourly services that stopped for it.

Authentication: an access token, sent as Authorization: Bearer <token>.

Fields of a 200 response:

GET /api/v1/billing/credit/ledger

Every time credit was used, newest first: the amount, the balance after, the service it was for and, for usage, the hours and meters it paid for. Hourly debits are here, which the credit balance's recent list does not show.

A debit that paid rated usage has kind usage and the first and last hour it covers (from, to), the hours and the meters. A flat hourly charge has hourly. Credit you added is not listed. Page with before. Answers 422 for a limit above 200. This is the platform account's own credit; an organization's owner reads its credit under /api/v1/orgs/{org_slug}/billing.

Authentication: an access token, sent as Authorization: Bearer <token>.

Fields of a 200 response:

POST /api/v1/billing/estimate

Price a month of App Deployment, game servers, Cloud Compute, Object Storage, SMTP Relay, mail and a domain, from the same price book as the order quote and the public estimator. Nothing is ordered or written.

Each component names a product and the inputs it reads (a server's size, hours_per_day and cpu_share, a web service's instances, memory_gib, requests_millions and egress_gb, and so on). The free amounts are those of a month nothing has used yet, and the first component to use a meter takes them. A server on a Free plan adds the Paid plan. account is your own plan unless you pass another to compare.

Answers 422 for a product, plan or cycle this list does not name, a number out of range, more than 20 components, or a size the price book does not sell (the answer names the sizes that exist). Amounts are in US dollars to the cent.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

Fields of a 200 response:

GET /api/v1/billing/events

What changed in how the account is billed, newest first: a price change (announced before it takes effect), a service moved between billing terms, a budget cap applied, a budget alert, a suspension for no credit and its resume. Each event has a title that says it in a sentence and the detail behind it. Page with before. Answers 422 for a limit above 100. These are the platform account's own events; an organization's owner reads its own under /api/v1/orgs/{org_slug}/billing/usage-cost.

Authentication: an access token, sent as Authorization: Bearer <token>.

Fields of a 200 response:

GET /api/v1/billing/invoices/{invoice_id}/usage

The usage lines of one invoice, each with its meter, its unit, the period it covers and the number of hours it adds up. The invoice answer shows a line as a description and a total; this opens it.

Send ?format=csv or Accept: text/csv for the hourly rows the invoice bills (the columns of GET /billing/usage/rows). Hours that were charged from credit before an invoice was made are not on the invoice and are not in it.

Answers 404 for an invoice that is not the account's, and an invoice with no usage lines answers an empty list. This is the platform account's own invoice; an organization's owner reads its customers' usage at /api/v1/orgs/{org_slug}/billing/usage-cost.

Authentication: an access token, sent as Authorization: Bearer <token>.

Fields of a 200 response:

GET /api/v1/billing/usage/rows

The hourly rows that a month's usage adds up from, newest hour first: the hour, the service, the meter, the quantity, the rate, the amount and its state. Filter by service, meter or state.

Send ?format=csv or Accept: text/csv for a file with the columns hour, service_id, service, meter, unit, quantity, included, billable, rate, amount, currency and status. A CSV holds at most 100000 rows: page with offset for more, and the X-Total-Rows header says how many match. A cell that a spreadsheet would run as a formula is written as text.

Answers 422 for a month that is not YYYY-MM, for a meter or state this list does not name, and for a JSON limit above 1000. A service that is not the account's, or is not billed by the second, has no rows. This is the platform account's own usage; an organization's owner reads what its customers cost at /api/v1/orgs/{org_slug}/billing/usage-cost.

Authentication: an access token, sent as Authorization: Bearer <token>.

Fields of a 200 response:

GET /api/v1/billing/usage/summary

What the account's services used and cost in a month: each service with its meters (quantity, included, billable and cost), the same month by day, how much of the free amounts is used and where the month is heading.

groups, pools, forecast, forecast_basis and spend_limit read as they do in GET /billing/compute-usage. services lists every service billed by the second that has use in the month, the dearest first; a server that is switched off says so in stopped and costs its disk only. daily has one row for each day and meter, summed over the services, so a chart can draw cost or use by day. included_share is the use of the free amounts as one figure from 0 to 1, weighted by their rates; the server amounts count only with the Paid plan.

A free server, a service on a flat price and an organization's customer's service are never listed. This is the platform account's own usage: an organization's owner reads its customers' usage at /api/v1/orgs/{org_slug}/billing/usage-cost. Answers 422 for a month that is not YYYY-MM.

Authentication: an access token, sent as Authorization: Bearer <token>.

Fields of a 200 response: