Model Pricing API

Base URL:

https://api.provon.dev/v1

Public routes use a project API key:

Authorization: Bearer <PROVON_API_KEY>

The default project key includes model-pricing:read.

Endpoints#

Signed-in Workbench calls use /v1/projects/:projectId/model-prices.... API integrations should normally use the routes above, where the key selects the project.

List Resolved Prices#

GET /v1/model-prices
Authorization: Bearer <PROVON_API_KEY>

Response:

{
  "models": [
    {
      "id": "openai:gpt-5-mini",
      "provider": "openai",
      "modelName": "gpt-5-mini",
      "matchPattern": "^gpt-5-mini(?:-|$)",
      "pricingTiers": [
        {
          "id": "standard",
          "name": "Standard",
          "isDefault": true,
          "priority": 0,
          "conditions": [],
          "prices": {
            "input_tokens": 2.5e-7,
            "output_tokens": 2e-6
          }
        }
      ],
      "source": "default",
      "editable": true,
      "resettable": false
    }
  ]
}

The list is already resolved for the project. A project override replaces or extends its base definition before the response is returned.

Prices are USD per chargeable unit. Token keys are normally per token, not per million tokens. For example, $0.25 / 1M input tokens is represented as 0.00000025.

Match A Model#

Use the match endpoint before relying on cost projections for a new model:

GET /v1/model-prices/match?provider=openai&model=gpt-5-mini-2026-06-01
Authorization: Bearer <PROVON_API_KEY>

Response:

{
  "match": {
    "model": {
      "id": "openai:gpt-5-mini",
      "provider": "openai",
      "modelName": "gpt-5-mini"
    },
    "pricingTier": {
      "id": "standard",
      "name": "Standard"
    },
    "source": "default"
  }
}

match is null when no definition matches. model is required; provider is optional but recommended when different providers reuse a model name.

Create A Custom Definition#

POST /v1/model-prices
Content-Type: application/json

{
  "provider": "external",
  "modelName": "acme-reasoner-v2",
  "matchPattern": "^acme-reasoner-v2(?:-|$)",
  "pricingTiers": [
    {
      "id": "standard",
      "name": "Standard",
      "isDefault": true,
      "priority": 0,
      "conditions": [],
      "prices": {
        "input_tokens": 8e-7,
        "output_tokens": 3.2e-6,
        "reasoning_output_tokens": 3.2e-6,
        "cache_read_input_tokens": 8e-8
      }
    }
  ]
}

Supported providers are:

openai
external
anthropic
google
xai
deepseek
alibaba
mistral
moonshot
minimax
zai

Common price keys are input_tokens, output_tokens, reasoning_output_tokens, cache_creation_input_tokens, and cache_read_input_tokens. Additional non-negative numeric keys are preserved for provider-specific usage detail.

Successful creation returns 201 with { "model": ... }.

Pricing Tiers#

Use tiers when price depends on a usage detail such as context length:

{
  "id": "long-context",
  "name": "Long context",
  "isDefault": false,
  "priority": 100,
  "conditions": [
    {
      "usageDetailPattern": "input_tokens",
      "operator": "gte",
      "value": 200000
    }
  ],
  "prices": {
    "input_tokens": 1.6e-6,
    "output_tokens": 6.4e-6
  }
}

Condition operators are gt, gte, lt, lte, eq, and neq. Non-default tiers are evaluated from the smallest priority number to the largest; one tier should be marked as the default fallback.

Override And Reset#

To override an existing default, create a project definition with baseModelPriceId set to the default definition ID. The returned source becomes project_override.

Update the project definition:

PATCH /v1/model-prices/:id

The update body uses the same complete shape as creation: provider, modelName, and a non-empty pricingTiers array are required.

Reset an override to its default:

POST /v1/model-prices/:id/reset

Delete a project-custom definition:

DELETE /v1/model-prices/:id

Both operations return:

{
  "ok": true
}

Cost Resolution#

Provon resolves cost in this order:

1. choose the project-resolved model definition by provider, exact name, or match pattern;
2. choose the highest-priority pricing tier whose conditions match usage details;
3. multiply each normalized usage bucket by its unit price;
4. write the model, tier, source, and cost breakdown into normalized telemetry.

If no model or required price key matches, the corresponding cost remains null. Provon does not invent a zero cost for unknown pricing.

Errors#

Related Docs#

• Model providers
• Gateway API
• Gateway observability
• Tracing attribute reference
• API reference