Daily cost by service, provider, or allocation

GET

/api/v1/costs/daily

const url = 'https://example.com/api/v1/costs/daily?groupBy=service';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://example.com/api/v1/costs/daily?groupBy=service'

Total daily BilledCost per selected grouping key, plus per-day and period totals. groupBy=service uses FOCUS ServiceName; groupBy=provider uses FOCUS ServiceProviderName; groupBy=allocation applies the query-time cost-allocation rules (virtual tagging) and keys each cost by its allocation label, with cost matching no rule under “Unallocated”. Ordering is deterministic: days ascending, keys sorted by name. Costs are decimal strings — never floats — so no precision is lost. When currency is absent, a single-currency range returns that series and currencies contains its one code; a mixed range defaults to the alphabetically-first currency’s series and currencies lists every available code. When currency is present, only that currency’s series is returned. A valid code absent from currencies returns 200 with total “0”, days [], and currency echoing the requested code. An empty range returns currencies [], currency “”, total “0”, and days []. An invalid currency shape returns 400.

Parameters

Query Parameters

start

string format: date

Inclusive first calendar day (UTC) to include. Defaults to the full range of stored data.

end

string format: date

Inclusive last calendar day (UTC) to include. Defaults to the full range of stored data.

groupBy

string

default: service

Allowed values: service provider allocation

Cost grouping dimension.

currency

string

/^[A-Z]{3}$/

Optional three-letter uppercase billing currency whose series to return. Omit to use the alphabetically-first currency in the range.

Responses

200

Daily costs grouped by the requested dimension for the requested period.

application/json

object

currency

required

Billing currency of this response’s series (FOCUS BillingCurrency): the currency query parameter when provided, otherwise the alphabetically-first currency in range, or “” when the range is empty.

string

currencies

required

All billing currencies with cost rows in the requested range, sorted ascending. This is the source for a currency selector and is [] (never null) when the range is empty.

Array<string>

days

required

One entry per calendar day with data, days ascending.

Array<object>

object

date

required

The UTC calendar day.

string format: date

total

required

Total cost of the day, as a decimal string.

string

services

required

Per-group costs, sorted by grouping key.

Array<object>

object

key

required

Grouping key: FOCUS ServiceName (groupBy=service), FOCUS ServiceProviderName (groupBy=provider), or the allocation label (groupBy=allocation; cost matching no rule appears under “Unallocated”).

string

cost

required

Cost total, as a decimal string.

string

total

required

Total cost of the whole period, as a decimal string.

string

Example

{
  "currency": "USD",
  "currencies": [
    "EUR",
    "USD"
  ],
  "days": [
    {
      "date": "2026-06-01",
      "total": "4.6809",
      "services": [
        {
          "key": "Amazon Elastic Compute Cloud",
          "cost": "2.4192"
        }
      ]
    }
  ],
  "total": "32.7663"
}

400

Invalid start date, end date, groupBy value, or currency shape; or groupBy=allocation was requested but no allocation rules are configured or the rules file was not found.

text/plain

string

500

The cost query failed, including an unreadable, malformed, or invalid allocation rules file (reported as “loading allocation rules: …”).

text/plain

string