---
title: "Upsert per-provider price overrides"
method: PUT
path: "/v1/projects/{project_id}/ai-providers/{ai_provider_id}/prices"
tags: ["AI Providers"]
---

# Upsert per-provider price overrides

`PUT /v1/projects/{project_id}/ai-providers/{ai_provider_id}/prices`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/projects/{project_id}/ai-providers/{ai_provider_id}/prices`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.naturali.ai/authorize`, token URL `https://api.naturali.ai/token`, scopes: `mcp:access`)

Upserts price overrides for this AI provider instance, keyed on (model, effective_from). The provider slug is taken from the AI provider itself, so only the model, rates, and effective_from are supplied. Authorized by the caller's access to the provider's project. `effective_from` must be in the future once the (model, component) has a price row — past prices are immutable, so corrections ship as new future-dated rows. A first price for a (model, component) nothing prices yet may be dated now or earlier, so a new provider is never live and unpriced.

## Path parameters

- `ai_provider_id` string, required

## Request body

- UpsertProviderPricesRequest
  - `prices` object[], required
    - `model` string, required
    - `component` string, required: The token component this row prices (`input_tokens`, `output_tokens`, `cached_tokens`, `cache_write_tokens`)
    - `unit` string, required: Always `token` for token pricing
    - `unit_price` number, required: USD per token for this component
    - `effective_from` string, date-time, required: Must be in the future; past prices are immutable

## Response `200`

The upserted price overrides

- ProviderPricesResponse
  - `prices` ProviderPrice[]
    - `id` string: Public ID of the price row
    - `ai_provider_id` string: The AI provider instance this override prices
    - `meter_type` string: Always `llm_tokens` for provider price overrides
    - `provider` string: Provider slug (taken from the AI provider instance)
    - `model` string
    - `component` string: The token component this row prices (`input_tokens`, `output_tokens`, `cached_tokens`, `cache_write_tokens`)
    - `unit` string: Always `token` for provider price overrides
    - `unit_price` number: USD per token for this component
    - `effective_from` string, date-time: The row with the latest effective_from <= now() prices a call
    - `created_at` string, date-time

## Other responses

- `400`: Bad Request (e.g. non-future effective_from)
- `401`: Unauthorized
- `403`: Forbidden
- `404`: AI provider not found

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)