Billing & metering

Event types, usage, entitlements, limits, and the billing endpoints.

StackResolve bills usage, not seats. Each expensive call records one usage event against your workspace. Cheap reads are free. All endpoints on this page need a valid key (Authentication).

#Plans

Plan	Price	Included per month
Starter	Free	Unlimited registry reads, 100 audits, 1,000 research calls, 1,000 tool-finds. No card. Usage stops at the limit.
Usage	Pay as you go	No monthly fee, no minimums. Per-call rates below. Set your own spend limits.
Scale	Custom	Volume rates, annual invoicing, SLAs. Talk to us.

#Per-call rates

Operation	Event type	Per call	Per 1k
Registry read (list, profile, search, compare)	none	Free	Free
Find tools for a task	`agent_discovery_check`	$0.005	$5
Company research (company, pricing, competitors, compare, research)	`workflow_execution`	$0.015	$15
Audit a product	`audit_run`	$0.03	$30

You are charged once per call, whether the answer is fresh or served from cache. See the full pricing page at /pricing.

#Metered event types

Three event types are wired to the API surface today.

Event type	Recorded by
`audit_run`	`/v1/audit`, the `audit` MCP tool, `stackresolve audit`
`workflow_execution`	`/v1/company`, `/v1/pricing`, `/v1/competitors`, `/v1/compare-companies`, `/v1/research`, and their MCP tools
`agent_discovery_check`	`/v1/find-tools`, the `find_tools_for_task` MCP tool

The usage taxonomy also reserves monitor_check, api_request, mcp_request, and browser_execution for later primitives. Plans and included quantities are configured per event type, so a new event type can be priced without an app change.

#How a metered call is settled

The call resolves your workspace from the x-api-key header.
It runs an entitlement check for the event type. If the included quantity is used up and overage is off, or a hard or spend limit is reached, the call returns 402 (Errors).
Otherwise the call runs and records one usage event, tagged with its source (api, mcp, or cli).

Pass an idempotency-key header to make a retry safe: a repeat with the same key does not double-record.

#GET /v1/usage

Your usage this billing period, per meter.

Shell

curl https://api.stackresolve.dev/v1/usage -H "x-api-key: $STACKRESOLVE_API_KEY"

Response (trimmed)

{
  "workspaceId": "ws_123",
  "plan": "free",
  "meteredEnabled": false,
  "period": { "start": "2026-08-01T00:00:00Z", "end": "2026-09-01T00:00:00Z" },
  "meters": [
    { "eventType": "audit_run", "included": 2, "used": 1, "remaining": 1, "billableOverage": 0, "overageEnabled": false, "estimatedChargeUsd": 0 },
    { "eventType": "workflow_execution", "included": 25, "used": 12, "remaining": 13, "billableOverage": 0, "overageEnabled": false, "estimatedChargeUsd": 0 },
    { "eventType": "agent_discovery_check", "included": 10, "used": 3, "remaining": 7, "billableOverage": 0, "overageEnabled": false, "estimatedChargeUsd": 0 }
  ],
  "estimatedChargesUsd": 0
}

The same summary is available as the get_usage MCP tool and stackresolve usage.

#GET /v1/entitlements

Included, used, and remaining per event type, plus whether each is allowed right now.

Response (trimmed)

{
  "entitlements": [
    { "eventType": "audit_run", "plan": "free", "allowed": true, "included": 25, "used": 3, "remaining": 22, "overageEnabled": false, "meteredEnabled": false, "hardLimit": null, "reason": "OK" }
  ]
}

#GET /v1/usage/events

Raw usage events, newest first. Filterable.

event_typestring

Filter to one event type.

product_idstring

Filter to one product.

fromstring

ISO timestamp, inclusive lower bound.

tostring

ISO timestamp, exclusive upper bound.

limitintegerdefault: 100

Max rows (capped at 500).

offsetintegerdefault: 0

Row offset for paging.

Shell

curl "https://api.stackresolve.dev/v1/usage/events?event_type=audit_run&limit=50" \
  -H "x-api-key: $STACKRESOLVE_API_KEY"

Response (trimmed)

{
  "events": [
    {
      "id": "evt_9",
      "event_type": "audit_run",
      "quantity": 1,
      "billable_quantity": 0,
      "source": "api",
      "provider_cost_usd": 0.0177,
      "occurred_at": "2026-08-20T08:47:13.253Z",
      "stripe_sync_status": "not_applicable"
    }
  ]
}

#GET and PATCH /v1/limits

Set spend guardrails. A warning is informational; a hard limit blocks further metered calls with 402 and reason SPEND_LIMIT_REACHED.

Get

curl https://api.stackresolve.dev/v1/limits -H "x-api-key: $STACKRESOLVE_API_KEY"

Set

curl -X PATCH https://api.stackresolve.dev/v1/limits \
  -H "x-api-key: $STACKRESOLVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"monthlyBudgetUsd": 50, "warningThresholdUsd": 40, "hardLimitUsd": 60, "notificationsEnabled": true}'

Response

{ "monthlyBudgetUsd": 50, "warningThresholdUsd": 40, "hardLimitUsd": 60, "notificationsEnabled": true }

monthlyBudgetUsdnumber

Soft monthly budget, or null to clear.

warningThresholdUsdnumber

Spend at which to warn, or null.

hardLimitUsdnumber

Spend at which to block metered calls, or null.

notificationsEnabledbooleandefault: true

Whether to send limit notifications.

#GET /v1/billing

Plan, current-period spend, and the estimated upcoming charge.

Response

{
  "plan": "usage",
  "meteredEnabled": true,
  "period": { "start": "2026-08-01T00:00:00Z", "end": "2026-09-01T00:00:00Z" },
  "spend": { "status": "OK", "spentUsd": 4.20, "monthlyBudgetUsd": 50, "warningThresholdUsd": 40, "hardLimitUsd": 60 },
  "estimatedUpcomingUsd": 4.20,
  "stripeConfigured": true
}

#Enable metered billing

Start a Stripe checkout, then manage the subscription in the portal.

Checkout

curl -X POST https://api.stackresolve.dev/v1/billing/checkout \
  -H "x-api-key: $STACKRESOLVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"successUrl": "https://yourapp.com/billing?ok=1", "cancelUrl": "https://yourapp.com/billing", "email": "you@yourapp.com"}'

The response holds a Stripe checkout url. Send the user there. After they subscribe, meteredEnabled becomes true and overage is billed against your plan.

Portal

curl -X POST https://api.stackresolve.dev/v1/billing/portal \
  -H "x-api-key: $STACKRESOLVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"returnUrl": "https://yourapp.com/billing"}'

successUrlstring

Where Stripe returns after a successful checkout.

cancelUrlstring

Where Stripe returns on cancel.

emailstring

Prefill the checkout email.

returnUrlstring

Portal only: where the portal returns.

Note

Checkout and portal return 503 when Stripe is not configured for the deployment.

#GET /v1/billing/invoices

Response

{ "invoices": [ { "id": "in_1", "amountDueUsd": 4.20, "status": "paid", "periodStart": "2026-07-01", "periodEnd": "2026-08-01" } ] }

Rate Limits: the anonymous trial and keyed gating.
Errors: the 402 and entitlement reason codes.
Caching: why a cache hit still records one event.

PreviousRate Limits

Billing & metering

#Plans

#Per-call rates

#Metered event types

#How a metered call is settled

#GET /v1/usage

#GET /v1/entitlements

#GET /v1/usage/events

#GET and PATCH /v1/limits

#GET /v1/billing

#Enable metered billing

#GET /v1/billing/invoices

#Related