Billing API¶

Manage workspace billing, metering, and payment methods. The billing API tracks action usage against plan limits, handles payment method collection via Stripe, and manages plan lifecycle transitions from trial through active subscription.

Get Billing Status¶

GET /api/billing

Returns the current billing status for the workspace, including plan state, usage counters, and payment method status.

curl https://api.runagents.io/api/billing \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY"

import requests

resp = requests.get(
    "https://api.runagents.io/api/billing",
    headers={"Authorization": f"Bearer {api_key}"},
)
print(resp.json())

Response (200 OK)¶

{
  "plan_status": "trial",
  "actions_used": 142,
  "actions_limit": 1000,
  "period_start": "2026-03-01T00:00:00Z",
  "period_end": "2026-03-31T00:00:00Z",
  "days_remaining": 24,
  "has_payment_method": false
}

Response Fields¶

Get Daily Usage¶

GET /api/billing/usage/daily

Returns daily action usage for the last 30 days. Useful for rendering usage charts and identifying consumption trends.

curl https://api.runagents.io/api/billing/usage/daily \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY"

import requests

resp = requests.get(
    "https://api.runagents.io/api/billing/usage/daily",
    headers={"Authorization": f"Bearer {api_key}"},
)
print(resp.json())

Response (200 OK)¶

[
  {"date": "2026-03-06", "count": 47},
  {"date": "2026-03-05", "count": 63},
  {"date": "2026-03-04", "count": 32}
]

Response Fields (per entry)¶

Create Setup Intent¶

POST /api/billing/setup-intent

Creates a Stripe SetupIntent for securely collecting a payment method. Use the returned client_secret with Stripe Elements on the frontend to confirm the card details without charging the user.

curl -X POST https://api.runagents.io/api/billing/setup-intent \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY"

import requests

resp = requests.post(
    "https://api.runagents.io/api/billing/setup-intent",
    headers={"Authorization": f"Bearer {api_key}"},
)
print(resp.json())

Response (200 OK)¶

{
  "client_secret": "seti_1N4k7p2eZvKYlo2C0lR3Pz5v_secret_OdN2LqKxvEqs2mYmKa0z7pM3sGnOA1L"
}

Response Fields¶

Attach Payment Method¶

POST /api/billing/payment-method

Attaches a payment method to the workspace after a SetupIntent has been confirmed on the frontend. For workspaces on the trial plan, this automatically transitions the plan to promo (3 months free).

Request Body¶

curl -X POST https://api.runagents.io/api/billing/payment-method \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payment_method_id": "pm_1N4k8q2eZvKYlo2CkFz7Ob3E"}'

import requests

resp = requests.post(
    "https://api.runagents.io/api/billing/payment-method",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"payment_method_id": "pm_1N4k8q2eZvKYlo2CkFz7Ob3E"},
)
print(resp.json())

Response (200 OK)¶

{
  "status": "promo"
}

Response Fields¶

Create Checkout Session¶

POST /api/billing/subscribe

Creates a Stripe Checkout session for subscribing to a paid plan. Redirects the user to Stripe's hosted checkout page.

Request Body¶

curl -X POST https://api.runagents.io/api/billing/subscribe \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://app.runagents.io/settings?billing=success",
    "cancel_url": "https://app.runagents.io/settings?billing=cancel"
  }'

import requests

resp = requests.post(
    "https://api.runagents.io/api/billing/subscribe",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "success_url": "https://app.runagents.io/settings?billing=success",
        "cancel_url": "https://app.runagents.io/settings?billing=cancel",
    },
)
print(resp.json())

Response (200 OK)¶

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_a1b2c3d4..."
}

Response Fields¶

Create Billing Portal Session¶

POST /api/billing/portal

Creates a Stripe Billing Portal session. The portal allows users to manage their subscription, update payment methods, and view invoice history.

Request Body¶

curl -X POST https://api.runagents.io/api/billing/portal \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"return_url": "https://app.runagents.io/settings"}'

import requests

resp = requests.post(
    "https://api.runagents.io/api/billing/portal",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"return_url": "https://app.runagents.io/settings"},
)
print(resp.json())

Response (200 OK)¶

{
  "url": "https://billing.stripe.com/p/session/live_a1b2c3d4..."
}

Response Fields¶

Get Publishable Key¶

GET /api/billing/publishable-key

Returns the Stripe publishable key for initializing Stripe Elements on the frontend. This key is safe to expose in client-side code.

curl https://api.runagents.io/api/billing/publishable-key \
  -H "Authorization: Bearer $RUNAGENTS_API_KEY"

import requests

resp = requests.get(
    "https://api.runagents.io/api/billing/publishable-key",
    headers={"Authorization": f"Bearer {api_key}"},
)
print(resp.json())

Response (200 OK)¶

{
  "publishable_key": "pk_live_51N4k7p2eZvKYlo2C..."
}

Response Fields¶

Plan Lifecycle¶

Workspace plans follow a state machine with automatic transitions based on time, usage, and payment events.

flowchart TD
    trial["Trial<br/>(30 days, 1000 actions)"]
    readonly["ReadOnly<br/>(30-day grace)"]
    promo["Promo<br/>(3 months free)"]
    active["Active<br/>($24/mo)"]
    suspended["Suspended"]
    deleted["Deleted"]

    trial -->|"No payment method"| readonly
    readonly -->|"Grace expires"| deleted
    trial -->|"Payment method added"| promo
    promo -->|"Promo period ends"| active
    active -->|"Payment failure"| suspended
    suspended -->|"Payment resolved"| active
    active -->|"Cancel subscription"| deleted

Transitions¶

Plan Status Reference¶