---
title: "Create a new model pricing definition"
method: POST
path: "/api/{org_id}/llm/models"
tags: ["LLM"]
---

# Create a new model pricing definition

`POST /api/{org_id}/llm/models`

## Request

- Base URL: `https://api.openobserve.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.openobserve.ai/api/{org_id}/llm/models`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/openobserve/apis/openobserve-api-http/docs/api/:org_id/llm/models/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new model pricing definition with regex match pattern and per-token pricing.

## Path parameters

- `org_id` string, required

## Request body

- ModelPricingDefinition: A model pricing definition that maps model names (via regex) to pricing tiers.
  - `children` object[]: Definitions shadowed by this one (same match_pattern, lower source/sort priority). Only populated in list responses — not stored in the database.
  - `created_at` integer: Created timestamp in microseconds
  - `description` string: Human-readable description. Populated for built-in entries.
  - `enabled` boolean: Whether this definition is active
  - `id` string, nullable: Unique identifier (KSUID)
  - `match_pattern` string: Regex pattern to match model names from incoming spans. Example: "(?i)^gpt-4o" or "(?i)^(claude-sonnet-4-6)$" Max length: 512 characters.
  - `name` string: Display name for the model (e.g., "GPT-4o", "Claude Sonnet 4.6")
  - `org_id` string: Organization ID
  - `provider` string: Provider name (e.g., "OpenAI", "Anthropic"). Populated for built-in entries.
  - `sort_order` integer: Explicit sort order for deterministic tie-breaking when multiple definitions match the same model name and have equal (or absent) `valid_from` values. Lower values are checked first; the first match wins. Defaults to 0 — set a lower number to make a definition take priority.
  - `source` 'built_in' | 'meta_org' | 'org': Ownership source of a model pricing definition.
  - `tiers` PricingTierDefinition[]: Pricing tiers; `ranks_tiers()` decides between first-match and highest-rank selection.
    - `condition` TierCondition: Condition for a pricing tier.
      - `operator` 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'neq': Comparison operators for tier conditions.
      - `usage_key` string: The usage key to evaluate (e.g., "input")
      - `value` number, double: Threshold value (e.g., 200000 for extended context pricing)
    - `name` string: Display name for this tier (e.g., "Default", "Extended Context")
    - `prices` object: Prices per token, keyed by usage type. Keys must exactly match usage keys produced by the span extractor: "input", "output", "cache_read_input_tokens", "cache_creation_input_tokens", etc. Values are price per single token (e.g., 0.000003 = $3/1M tokens). **Precision note:** `f64` provides ~15 significant decimal digits, which is more than sufficient for cost *estimation* on observability data. These values are not used for billing or financial accounting — they produce approximate cost figures for dashboards and alerts. The multiplication `token_count as f64 * price` is exact for token counts < 2^53 (~9 quadrillion), well beyond practical span sizes.
    - `priority` integer: Breaks ties between matching tiers before the restriction count; higher wins.
    - `rules` TierRule[]: Span-attribute rules (service tier, speed, region) that must all hold.
      - `keys` string[]: Attribute keys tried in order; compared ignoring case and `_`/`-`/`.` separators.
      - `op` 'in' | 'not_in' | 'exists' | 'not_exists' | 'gt' | 'gte' | 'lt' | 'lte' | 'unknown': Operators for [`TierRule`].
      - `value` number, double, nullable: Threshold for the numeric operators.
      - `values` string[]: Accepted values for `in` / `not_in`, compared trimmed and case-insensitively.
    - `utc_windows` UtcTimeWindow[]: Recurring UTC time-of-day windows during which this tier applies. Empty (the default) means the tier is not time-restricted. Providers such as DeepSeek publish "peak" and "off-peak" rates that repeat every day, which is a time-of-day range rather than an absolute cutover (that is what `valid_from` is for). A tier applies when the span falls in ANY of its windows *and* its `condition` (if set) passes, so windows compose with context-length tiering.
      - `end_minute` integer: Exclusive end, minutes since UTC midnight (0–1440).
      - `start_minute` integer: Inclusive start, minutes since UTC midnight (0–1440).
  - `updated_at` integer: Updated timestamp in microseconds
  - `valid_from` integer, nullable: Optional Unix timestamp (microseconds) from which this definition is valid. When multiple definitions match the same model name, the one with the greatest `valid_from` that is still <= the span's start time is used. If None, the definition is valid for all time.

## Response `201`

Created

- ModelPricingDefinition: A model pricing definition that maps model names (via regex) to pricing tiers.
  - `children` object[]: Definitions shadowed by this one (same match_pattern, lower source/sort priority). Only populated in list responses — not stored in the database.
  - `created_at` integer: Created timestamp in microseconds
  - `description` string: Human-readable description. Populated for built-in entries.
  - `enabled` boolean: Whether this definition is active
  - `id` string, nullable: Unique identifier (KSUID)
  - `match_pattern` string: Regex pattern to match model names from incoming spans. Example: "(?i)^gpt-4o" or "(?i)^(claude-sonnet-4-6)$" Max length: 512 characters.
  - `name` string: Display name for the model (e.g., "GPT-4o", "Claude Sonnet 4.6")
  - `org_id` string: Organization ID
  - `provider` string: Provider name (e.g., "OpenAI", "Anthropic"). Populated for built-in entries.
  - `sort_order` integer: Explicit sort order for deterministic tie-breaking when multiple definitions match the same model name and have equal (or absent) `valid_from` values. Lower values are checked first; the first match wins. Defaults to 0 — set a lower number to make a definition take priority.
  - `source` 'built_in' | 'meta_org' | 'org': Ownership source of a model pricing definition.
  - `tiers` PricingTierDefinition[]: Pricing tiers; `ranks_tiers()` decides between first-match and highest-rank selection.
    - `condition` TierCondition: Condition for a pricing tier.
      - `operator` 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'neq': Comparison operators for tier conditions.
      - `usage_key` string: The usage key to evaluate (e.g., "input")
      - `value` number, double: Threshold value (e.g., 200000 for extended context pricing)
    - `name` string: Display name for this tier (e.g., "Default", "Extended Context")
    - `prices` object: Prices per token, keyed by usage type. Keys must exactly match usage keys produced by the span extractor: "input", "output", "cache_read_input_tokens", "cache_creation_input_tokens", etc. Values are price per single token (e.g., 0.000003 = $3/1M tokens). **Precision note:** `f64` provides ~15 significant decimal digits, which is more than sufficient for cost *estimation* on observability data. These values are not used for billing or financial accounting — they produce approximate cost figures for dashboards and alerts. The multiplication `token_count as f64 * price` is exact for token counts < 2^53 (~9 quadrillion), well beyond practical span sizes.
    - `priority` integer: Breaks ties between matching tiers before the restriction count; higher wins.
    - `rules` TierRule[]: Span-attribute rules (service tier, speed, region) that must all hold.
      - `keys` string[]: Attribute keys tried in order; compared ignoring case and `_`/`-`/`.` separators.
      - `op` 'in' | 'not_in' | 'exists' | 'not_exists' | 'gt' | 'gte' | 'lt' | 'lte' | 'unknown': Operators for [`TierRule`].
      - `value` number, double, nullable: Threshold for the numeric operators.
      - `values` string[]: Accepted values for `in` / `not_in`, compared trimmed and case-insensitively.
    - `utc_windows` UtcTimeWindow[]: Recurring UTC time-of-day windows during which this tier applies. Empty (the default) means the tier is not time-restricted. Providers such as DeepSeek publish "peak" and "off-peak" rates that repeat every day, which is a time-of-day range rather than an absolute cutover (that is what `valid_from` is for). A tier applies when the span falls in ANY of its windows *and* its `condition` (if set) passes, so windows compose with context-length tiering.
      - `end_minute` integer: Exclusive end, minutes since UTC midnight (0–1440).
      - `start_minute` integer: Inclusive start, minutes since UTC midnight (0–1440).
  - `updated_at` integer: Updated timestamp in microseconds
  - `valid_from` integer, nullable: Optional Unix timestamp (microseconds) from which this definition is valid. When multiple definitions match the same model name, the one with the greatest `valid_from` that is still <= the span's start time is used. If None, the definition is valid for all time.

## Other responses

- `400`: Bad request

---

[API](https://skmtc.dev/openobserve/apis/openobserve-api-http.md) - [All operations](https://skmtc.dev/openobserve/apis/openobserve-api-http/llms.txt) - [OpenAPI document](https://skmtc.dev/openobserve/apis/openobserve-api-http/revisions/0529b8a10252?raw)