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",
      "modelId": "gpt-5-mini",
      "providerId": null,
      "catalogId": "openai/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-price-matches?providerId=openai&model=gpt-5-mini
Authorization: Bearer <PROVON_API_KEY>

Response:

{
  "match": {
    "model": {
      "id": "openai:gpt-5-mini",
      "modelId": "gpt-5-mini",
      "providerId": null,
      "catalogId": "openai/gpt-5-mini"
    },
    "pricingTier": {
      "id": "standard",
      "name": "Standard"
    },
    "source": "default"
  }
}

match is null when no definition matches. model is required. A qualified value such as custom/gpt-5-mini supplies both the provider ID and model ID; otherwise the optional providerId query parameter supplies the provider ID.

Create A Custom Definition#

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

{
  "providerId": "acme",
  "modelId": "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
      }
    }
  ]
}

providerId scopes a project-custom price to one Gateway provider. Provider IDs are normalized case-insensitively. modelId is an unqualified model identifier and must not contain /.

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/:modelPriceId

The update body uses the same complete shape as creation: modelId and a non-empty pricingTiers array are required. providerId is required for project-custom prices and remains null for overrides of an unscoped default price.

Reset an override to its default:

DELETE /v1/model-prices/:modelPriceId/override

Delete a project-custom definition:

DELETE /v1/model-prices/:modelPriceId

Both operations return:

{
  "ok": true
}

Cost Resolution#

Provon resolves cost in this order:

1. parse the observed value into a provider ID and model ID;
2. choose an exact provider-scoped price when one exists;
3. otherwise choose the unscoped default price for the model ID;
4. choose the highest-priority pricing tier whose conditions match usage details;
5. multiply each normalized usage bucket by its unit price;
6. 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#