Billing

The billing service exposes read access to your account’s metered usage — both the current billing period and a 12-month history broken down by individual agent. Use it to render usage charts, build internal cost-attribution reports, or warn users before they cross a paid-tier threshold.

Service: firetiger.billing.v1.BillingService

Access: Read-only

Example flow

Read the current period’s headline counters, then pull a 6-month per-agent history for a cost-attribution view.

1. Get current-period usage

curl -X POST "https://api.cloud.firetiger.com/firetiger.billing.v1.BillingService/GetBillingUsage" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "agentOperationCount": "8430",
  "agentOperationLimit": "25000",
  "periodStart": "2024-06-01T00:00:00Z",
  "periodEnd": "2024-07-01T00:00:00Z",
  "dailyFreeUsage": "120",
  "dailyFreeLimit": "300",
  "paidUsage": "1530",
  "paidLimit": "25000",
  "periodUsageBySource": [
    {"sourceType": "BILLING_EVENT_SOURCE_CHANGE_MONITOR", "paidOperationCount": "900"},
    {"sourceType": "BILLING_EVENT_SOURCE_CUSTOM_AGENT", "paidOperationCount": "500"},
    {"sourceType": "BILLING_EVENT_SOURCE_INVESTIGATION", "paidOperationCount": "130"}
  ]
}

2. List the last 6 months of per-agent usage

curl -X POST "https://api.cloud.firetiger.com/firetiger.billing.v1.BillingService/ListUsageHistory" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"months": 6}'

{
  "months": [
    {
      "periodStart": "2024-01-01T00:00:00Z",
      "periodEnd": "2024-02-01T00:00:00Z",
      "totalOperations": "4200",
      "paidOperations": "600",
      "estimatedCostCents": "2000",
      "byAgent": [
        {
          "source": "agents/my-agent",
          "sourceType": "BILLING_EVENT_SOURCE_CUSTOM_AGENT",
          "displayName": "Production change monitor",
          "totalOperations": "3000",
          "paidOperations": "450"
        },
        {
          "source": "investigations",
          "sourceType": "BILLING_EVENT_SOURCE_INVESTIGATION",
          "displayName": "Investigations",
          "totalOperations": "1200",
          "paidOperations": "150"
        }
      ]
    }
  ]
}

Methods

Method Description
GetBillingUsage Read current-period usage with a per-surface breakdown
ListUsageHistory List per-month, per-agent historical usage with estimated cost

GetBillingUsage

Reports metered usage for the current billing period — daily free credits (300/day, resets at UTC midnight), paid allocation, and period boundaries. Use this to render a usage meter or to decide whether to throttle agent kicks before overage.

POST /firetiger.billing.v1.BillingService/GetBillingUsage

Request body

No fields. The account is identified from the authenticated session.

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.billing.v1.BillingService/GetBillingUsage" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

Field Type Description
agentOperationCount int64 Total operations metered in the current period across all sources
agentOperationLimit int64 The headline operation limit applied to this account (plan-dependent)
periodStart timestamp Inclusive UTC midnight start of the current billing period
periodEnd timestamp Exclusive UTC midnight end of the current billing period
dailyFreeUsage int64 Operations counted against today’s free-credit pool
dailyFreeLimit int64 The daily free-credit allowance (300)
paidUsage int64 Operations above the per-day free credit, summed across days in this period
paidLimit int64 Paid-allocation ceiling for this plan (0 for free accounts — all overage bills)
periodUsageBySource repeated UsageBySource Paid operations split by product surface (change monitor / custom agent / investigation)

UsageBySource fields:

Field Type Description
sourceType BillingEventSource Product surface that produced the operations
paidOperationCount int64 Paid operations attributable to this source after pro-rata allocation of the daily free credit. Summing across rows equals paidUsage. 
{
  "agentOperationCount": "8430",
  "agentOperationLimit": "25000",
  "periodStart": "2024-06-01T00:00:00Z",
  "periodEnd": "2024-07-01T00:00:00Z",
  "dailyFreeUsage": "120",
  "dailyFreeLimit": "300",
  "paidUsage": "1530",
  "paidLimit": "25000",
  "periodUsageBySource": [
    {"sourceType": "BILLING_EVENT_SOURCE_CHANGE_MONITOR", "paidOperationCount": "900"},
    {"sourceType": "BILLING_EVENT_SOURCE_CUSTOM_AGENT", "paidOperationCount": "500"},
    {"sourceType": "BILLING_EVENT_SOURCE_INVESTIGATION", "paidOperationCount": "130"}
  ]
}

ListUsageHistory

Returns per-month usage with a per-agent breakdown for the last N billing periods. Investigation events are rolled up into a single synthetic entry per period (source = "investigations"), since individual investigation IDs are ephemeral.

POST /firetiger.billing.v1.BillingService/ListUsageHistory

Request body

Field Type Required Description
months int32 No Number of recent billing periods to return. Defaults to 12, clamped to [1, 24].

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.billing.v1.BillingService/ListUsageHistory" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"months": 6}'

Response

Field Type Description
months repeated MonthlyUsage One entry per billing period that contains usage in the requested window, oldest-first. May be shorter than the requested months if the account is younger than that.

MonthlyUsage fields:

Field Type Description
periodStart timestamp Inclusive UTC midnight start of the billing period
periodEnd timestamp Exclusive UTC midnight end of the billing period
totalOperations int64 Total operations metered in this period across all sources
paidOperations int64 Operations after the 300/day free credit, summed across sources
estimatedCostCents int64 Estimated total dollar cost for this period (base subscription + overage), in cents. Computed as current_base_plan_per_month + ceil(max(paid_operations − included_allocation, 0) / 600) × current overage rate, where included_allocation is what the plan bundles into its base fee (0 for Bootstrap/free, 25,000 for Growth). Uses the current plan and rates against historical paid operations — it’s an estimate, not an invoice. Annual subscriptions are divided by 12 so each monthly bucket reflects one month’s share.
byAgent repeated AgentUsage Per-agent breakdown, sorted by totalOperations descending

AgentUsage fields:

Field Type Description
source string Resource path of the originating agent, e.g. agents/my-agent. The synthetic value investigations represents the rolled-up investigations bucket.
sourceType BillingEventSource Source-type classification carried through for tooltip / filter use
displayName string Human-readable label. Falls back to the source path when the agent’s title can’t be resolved (e.g. it was deleted).
totalOperations int64 Total operations attributed to this agent in the period
paidOperations int64 Operations after the pro-rata daily free-credit allocation. Summing across byAgent rows equals MonthlyUsage.paidOperations. 
{
  "months": [
    {
      "periodStart": "2024-01-01T00:00:00Z",
      "periodEnd": "2024-02-01T00:00:00Z",
      "totalOperations": "4200",
      "paidOperations": "600",
      "estimatedCostCents": "2000",
      "byAgent": [
        {
          "source": "agents/my-agent",
          "sourceType": "BILLING_EVENT_SOURCE_CUSTOM_AGENT",
          "displayName": "Production change monitor",
          "totalOperations": "3000",
          "paidOperations": "450"
        },
        {
          "source": "investigations",
          "sourceType": "BILLING_EVENT_SOURCE_INVESTIGATION",
          "displayName": "Investigations",
          "totalOperations": "1200",
          "paidOperations": "150"
        }
      ]
    }
  ]
}

BillingEventSource

Classifies a billable operation by the product surface that produced it.

Value Description
BILLING_EVENT_SOURCE_UNSPECIFIED Unknown / legacy event with no recorded source
BILLING_EVENT_SOURCE_CHANGE_MONITOR Operations triggered by a change monitor (monitoring plan authoring or execution)
BILLING_EVENT_SOURCE_CUSTOM_AGENT Operations from user-created custom agents
BILLING_EVENT_SOURCE_INVESTIGATION Operations from the investigations surface
This site uses Just the Docs, a documentation theme for Jekyll.