Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.secapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Agent Billing

​
Principle

Agents should not treat billing as an afterthought. They should inspect billing posture before expensive loops, preserve billing metadata in outputs, and warn before they cross from cheap reads into repeated or heavy workflows.

​
Required checks

Before a multi-step workflow:
  • GET /v1/billing
  • GET /v1/limits
  • POST /v1/billing/quote for the expensive step you are about to repeat

​
Agent-safe behavior

  • prefer one targeted request over a wide fan-out
  • keep Request-Id, traceparent, Omni-Meter-Class, Omni-Plan-Key, Omni-Billing-State, Omni-Free-Grant-Remaining, Omni-Token-Count, and Omni-Estimated-Cost
  • warn before repeated section extraction, compare workflows, or artifact generation
  • stop and ask for card attachment if the org is in payg_pending_card
  • stop and ask for operator approval if the server returns billing_budget_approval_required
  • stop immediately if the server returns billing_budget_hard_cap_exceeded
  • human operators create sponsor tokens with POST /v1/agent/bootstrap_tokens
  • agents exchange those tokens exactly once with POST /v1/agent/bootstrap
  • the bootstrap response returns the first API key, billing posture, limits, and MCP install metadata in one payload

​
Good pattern

Check billing posture first. Quote the expensive step before repeating it. If the org is still on the starter grant, use the smallest high-signal request sequence possible. If the org is in payg_pending_card, stop and ask the operator to activate PAYG before continuing. If the server requires approval or reports a hard cap, stop instead of retrying blindly.