Billing

Usage & Cost

GET
/api/usage

Retrieve your workspace’s usage and cost for a time window — the same per-request-type breakdown shown in the dashboard, available with your API key. Use it to reconcile billing or power an internal usage dashboard.

Usage is aggregated across every Environment in the workspace; it is not scoped to a single Environment or API key.

Choosing a Window

Set the window with a period (trailing days, 1–365, default 30) or an explicit from/to range — never both. from and to are inclusive, must be sent together with from no later than to or today, and can span at most 365 days. Set them to the same day to read a single day’s usage.

Cost

Each request type returns a count and a cost_micros.

Next Steps

Check One Event

Submit Events that this usage counts.

Policies

See how each checked Event maps to a request type.

Authorizations

  • Authorizationstringheaderrequired

    API Key required. Format: Bearer wc-your-api-key

Headers

  • whitecircle-versionstringrequired

    API Version

    Example: "2026-06-01"

Query Parameters

  • periodinteger<int32> | null

    Trailing window in days (1–365). Mutually exclusive with from/to. Defaults to 30.

    Required range: 1 <= x <= 365

  • fromstring<date> | null

    Inclusive start day (YYYY-MM-DD). Requires to. Mutually exclusive with period.

  • tostring<date> | null

    Inclusive end day (YYYY-MM-DD). Requires from. Mutually exclusive with period.

Response

application/json

Success

  • fromstring<date>required

    Inclusive first day covered (YYYY-MM-DD).

  • tostring<date>required

    Inclusive last day covered (YYYY-MM-DD).

  • messageobjectrequired

    Show child attributes
    • message.countinteger<int64>required

      Number of checks in this category.

      Required range: x >= 0

    • message.cost_microsinteger<int64>required

      Cost in millionths of one USD (divide by 1,000,000 for dollars).

  • artifactobjectrequired

    Show child attributes
    • artifact.imageobjectrequired

      Show child attributes
      • artifact.image.countinteger<int64>required

        Number of checks in this category.

        Required range: x >= 0

      • artifact.image.cost_microsinteger<int64>required

        Cost in millionths of one USD (divide by 1,000,000 for dollars).

    • artifact.videoobjectrequired

      Video artifact checks are counted but not billed.

      Show child attributes
      • artifact.video.countinteger<int64>required

        Number of checks in this category.

        Required range: x >= 0

      • artifact.video.cost_microsinteger<int64>required

        Cost in millionths of one USD (divide by 1,000,000 for dollars).

    • artifact.websiteobjectrequired

      Website artifact checks are counted but not billed.

      Show child attributes
      • artifact.website.countinteger<int64>required

        Number of checks in this category.

        Required range: x >= 0

      • artifact.website.cost_microsinteger<int64>required

        Cost in millionths of one USD (divide by 1,000,000 for dollars).

  • toolobjectrequired

    Show child attributes
    • tool.countinteger<int64>required

      Number of checks in this category.

      Required range: x >= 0

    • tool.cost_microsinteger<int64>required

      Cost in millionths of one USD (divide by 1,000,000 for dollars).

  • agentobjectrequired

    Show child attributes
    • agent.countinteger<int64>required

      Number of checks in this category.

      Required range: x >= 0

    • agent.cost_microsinteger<int64>required

      Cost in millionths of one USD (divide by 1,000,000 for dollars).

  • functionobjectrequired

    Show child attributes
    • function.countinteger<int64>required

      Number of checks in this category.

      Required range: x >= 0

    • function.cost_microsinteger<int64>required

      Cost in millionths of one USD (divide by 1,000,000 for dollars).

  • reasoningobjectrequired

    Show child attributes
    • reasoning.countinteger<int64>required

      Number of checks in this category.

      Required range: x >= 0

    • reasoning.cost_microsinteger<int64>required

      Cost in millionths of one USD (divide by 1,000,000 for dollars).

  • total_microsinteger<int64>required

    Total cost across all categories, in millionths of one USD.