--- title: "read_model_prices" description: "Generated reference for the management action read_model_prices: its description, access metadata, payload contract, and registration status." slug: /reference/actions/read-model-prices order: 97 visibility: public redirects_from: [] --- # read\_model\_prices Generated automatically from the [published contract sources](/reference/about#contract-sources). **Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured. A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/actions/read_model_prices`, with a bearer credential and the action's payload as the JSON body. It also accepts `GET`. ## Contract description Read the platform's price table for the AI allowance: every row, or the named \`model\`'s rows\. Super\-admin \(platform operator\) only\. Each row carries its rates in US dollars per million tokens, its long\-context tier where it has one, the date it took effect, its source, its stamp, and its author\. The row in effect for a model is its newest whose effective date has passed\. Earlier rows stand as history, since a call is priced once at the row in effect at its instant\. ## Access and action metadata ```json { "name": "read_model_prices", "resource": "account", "tier": "observe", "grant": "super_admin", "summary": "Super-admin: the AI allowance's price table — every row, or the named `model`'s rows — each row with its rates in US dollars per million tokens, its long-context tier where it has one, the date it took effect, its source, its stamp, and its author, the row in effect for a model being its newest whose effective date has passed and the earlier rows standing as history, since a call is priced once at the row in effect at its instant.", "annotations": { "readOnlyHint": true, "destructiveHint": false, "openWorldHint": false, "idempotentHint": true } } ``` ## MCP catalog entry ```json { "name": "read_model_prices", "title": "Read model prices", "tier": "observe", "scenario": "API-L0-12", "summary": "Read the platform's price table for the AI allowance: every row, or the named `model`'s rows. Super-admin (platform operator) only. Each row carries its rates in US dollars per million tokens, its long-context tier where it has one, the date it took effect, its source, its stamp, and its author. The row in effect for a model is its newest whose effective date has passed. Earlier rows stand as history, since a call is priced once at the row in effect at its instant.", "owners": [ "EGW-L0-06", "API-L0-12" ] } ``` ## request | JSON pointer | Description and constraints | |---|---| | "" \(root\) | Type: object
Additional properties: false | | /properties/model | Answers that model's rows alone, newest first\. A call naming no \`model\` answers every row of the table\.

Type: string | ## response | JSON pointer | Description and constraints | |---|---| | "" \(root\) | The allowance's price table: the provider's published prices per Gemini model, in US dollars per million tokens, seeded by migration from the provider's list and appended to by \`set\_model\_price\`\. The figures are the provider's facts and no value of the pricing registry, whose allowance row records the table's provenance\.

Type: object
Required fields: \["contract\_version","prices"\]
Additional properties: false | | /properties/contract\_version | Required value: 1 | | /properties/prices | The rows of the price table the call selected, by model and then newest first\. The row in effect for a model is its newest whose \`effective\_from\` has passed; earlier rows stand as history, since a call is priced once at the row in effect at its instant\.

Type: array | | /properties/prices/items | Type: object
Required fields: \["model","input\_usd\_per\_million","cached\_input\_usd\_per\_million","audio\_input\_usd\_per\_million","output\_usd\_per\_million","image\_output\_usd\_per\_million","long\_context\_input\_usd\_per\_million","long\_context\_output\_usd\_per\_million","long\_context\_threshold\_tokens","effective\_from","source","set\_at","set\_by"\] | | /properties/prices/items/properties/model | The Gemini model name the row prices, spelled as a call names it in the allowance route's path, opening with \`gemini\-\`\.

Type: string
Pattern: ^gemini\-\[a\-z0\-9\.\-\]\+$ | | /properties/prices/items/properties/input\_usd\_per\_million | US dollars per million prompt tokens of text, image, or video, to six places, the provider's published figure\.

Type: number
Minimum: 0 | | /properties/prices/items/properties/cached\_input\_usd\_per\_million | US dollars per million prompt tokens the provider serves from its cache, to six places, the provider's published cached\-input figure\. Null or absent draws cached tokens at the input rate\.

Type: \["number","null"\]
Minimum: 0 | | /properties/prices/items/properties/audio\_input\_usd\_per\_million | US dollars per million prompt tokens of audio, where the provider prices audio apart; null or absent prices audio at the input rate\.

Type: \["number","null"\]
Minimum: 0 | | /properties/prices/items/properties/output\_usd\_per\_million | US dollars per million output tokens, thinking tokens among them, the provider's published figure\.

Type: number
Minimum: 0 | | /properties/prices/items/properties/image\_output\_usd\_per\_million | US dollars per million image output tokens; the provider's per\-image price is the image's tokens at this rate\. Null or absent for a model that generates no image\.

Type: \["number","null"\]
Minimum: 0 | | /properties/prices/items/properties/long\_context\_input\_usd\_per\_million | The input rate for a prompt whose tokens pass \`long\_context\_threshold\_tokens\`; null or absent where the model has no long\-context tier\.

Type: \["number","null"\]
Minimum: 0 | | /properties/prices/items/properties/long\_context\_output\_usd\_per\_million | The output rate for a call whose prompt passes the threshold; null or absent where the model has no long\-context tier\.

Type: \["number","null"\]
Minimum: 0 | | /properties/prices/items/properties/long\_context\_threshold\_tokens | The prompt token count past which the long\-context rates apply; null or absent where the model has no long\-context tier\.

Type: \["integer","null"\]
Minimum: 1 | | /properties/prices/items/properties/effective\_from | The UTC date, \`YYYY\-MM\-DD\`, from which the row prices calls, the provider's own effective date\. A row is appended and never rewritten: the row in effect at a call's instant is the model's newest whose date has passed\.

Type: string | | /properties/prices/items/properties/source | Where the figures were read: the provider's price list's address and the date it was read, recorded with the row\.

Type: string | | /properties/prices/items/properties/set\_at | the write's instant, ISO 8601 in UTC

Type: string | | /properties/prices/items/properties/set\_by | the operator's account id; seed for a row the migration wrote

Type: string | | /properties/detail | What the rows are, which row prices a call, and how an unpriced model is metered\.

Type: string | ## Complete payload contract ```json { "request": { "type": "object", "properties": { "model": { "type": "string", "description": "Answers that model's rows alone, newest first. A call naming no `model` answers every row of the table." } }, "additionalProperties": false }, "response": { "type": "object", "required": [ "contract_version", "prices" ], "properties": { "contract_version": { "const": 1 }, "prices": { "type": "array", "items": { "type": "object", "required": [ "model", "input_usd_per_million", "cached_input_usd_per_million", "audio_input_usd_per_million", "output_usd_per_million", "image_output_usd_per_million", "long_context_input_usd_per_million", "long_context_output_usd_per_million", "long_context_threshold_tokens", "effective_from", "source", "set_at", "set_by" ], "properties": { "model": { "type": "string", "pattern": "^gemini-[a-z0-9.-]+$", "description": "The Gemini model name the row prices, spelled as a call names it in the allowance route's path, opening with `gemini-`." }, "input_usd_per_million": { "type": "number", "minimum": 0, "description": "US dollars per million prompt tokens of text, image, or video, to six places, the provider's published figure." }, "cached_input_usd_per_million": { "type": [ "number", "null" ], "minimum": 0, "description": "US dollars per million prompt tokens the provider serves from its cache, to six places, the provider's published cached-input figure. Null or absent draws cached tokens at the input rate." }, "audio_input_usd_per_million": { "type": [ "number", "null" ], "minimum": 0, "description": "US dollars per million prompt tokens of audio, where the provider prices audio apart; null or absent prices audio at the input rate." }, "output_usd_per_million": { "type": "number", "minimum": 0, "description": "US dollars per million output tokens, thinking tokens among them, the provider's published figure." }, "image_output_usd_per_million": { "type": [ "number", "null" ], "minimum": 0, "description": "US dollars per million image output tokens; the provider's per-image price is the image's tokens at this rate. Null or absent for a model that generates no image." }, "long_context_input_usd_per_million": { "type": [ "number", "null" ], "minimum": 0, "description": "The input rate for a prompt whose tokens pass `long_context_threshold_tokens`; null or absent where the model has no long-context tier." }, "long_context_output_usd_per_million": { "type": [ "number", "null" ], "minimum": 0, "description": "The output rate for a call whose prompt passes the threshold; null or absent where the model has no long-context tier." }, "long_context_threshold_tokens": { "type": [ "integer", "null" ], "minimum": 1, "description": "The prompt token count past which the long-context rates apply; null or absent where the model has no long-context tier." }, "effective_from": { "type": "string", "description": "The UTC date, `YYYY-MM-DD`, from which the row prices calls, the provider's own effective date. A row is appended and never rewritten: the row in effect at a call's instant is the model's newest whose date has passed." }, "source": { "type": "string", "description": "Where the figures were read: the provider's price list's address and the date it was read, recorded with the row." }, "set_at": { "type": "string", "description": "the write's instant, ISO 8601 in UTC" }, "set_by": { "type": "string", "description": "the operator's account id; seed for a row the migration wrote" } } }, "description": "The rows of the price table the call selected, by model and then newest first. The row in effect for a model is its newest whose `effective_from` has passed; earlier rows stand as history, since a call is priced once at the row in effect at its instant (EGW-L0-06)." }, "detail": { "type": "string", "description": "What the rows are, which row prices a call, and how an unpriced model is metered." } }, "additionalProperties": false, "description": "The allowance's price table: the provider's published prices per Gemini model, in US dollars per million tokens, seeded by migration from the provider's list and appended to by `set_model_price`. The figures are the provider's facts and no value of the pricing registry, whose allowance row records the table's provenance (PRC-L0-01)." } } ``` ## Shared contracts - [Refusals](/reference/refusals): every refusal, by surface, with its cause and its remedy - [schemas/wire\_error\.schema\.json](/reference/sources/schemas/wire-error-schema) - [schemas/wire\_errors\.json](/reference/sources/schemas/wire-errors) - [schemas/action\_payloads\.json](/reference/sources/schemas/action-payloads) (includes shared shapes) - [management\_api\_contract\.md](/reference/sources/management-api-contract)