Ramp: AI spend schemas
20 Ramp schemas with complete fields and constraints.
← AI spend operations · All schemas
List AI usage and estimated spend grouped by the requested dimensions — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | array | Required within parent | Resources returned in this page. |
data[] | Model | Each item | Expand List AI usage and estimated spend grouped by the requested dimensions — response body — data item |
page | Model | Required within parent | Expand List bills — response body — page Pagination details for this response. |
Referenced models: List bills — response body — page, List AI usage and estimated spend grouped by the requested dimensions — response body — data item
List AI usage and estimated spend grouped by the requested dimensions — response body — data item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
cached_input_tokens | JSON | Required within parent | |
cached_input_tokens (anyOf 1) | integer | Alternative | Number of cached input tokens. |
cached_input_tokens (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
department_id | JSON | Required within parent | |
department_id (anyOf 1) | string | Alternative | Department of the Ramp user. Null unless group_by includes department, or when the user has no department. Format: uuid |
department_id (anyOf 2) | null | Alternative | |
estimated_cost | JSON | Required within parent | |
estimated_cost (anyOf 1) | Model | Alternative | Expand Fetch a payment — response body — amount Estimated cost, matching the AI Spend page. Null for AWS Bedrock, which Ramp reports as billed cost rather than an estimate. When rows combine AWS Bedrock with other providers, the estimate excludes AWS Bedrock. Read only: true |
estimated_cost (anyOf 2) | null | Alternative | |
input_tokens | JSON | Required within parent | |
input_tokens (anyOf 1) | integer | Alternative | Number of input tokens. |
input_tokens (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
model | JSON | Required within parent | |
model (anyOf 1) | string | Alternative | Provider model name. Null unless group_by includes model, or when the provider did not report one. |
model (anyOf 2) | null | Alternative | |
output_tokens | JSON | Required within parent | |
output_tokens (anyOf 1) | integer | Alternative | Number of output tokens. |
output_tokens (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
product | JSON | Required within parent | |
product (anyOf 1) | string | Alternative | Product the usage came from, such as claude_code, codex, or cursor. Null unless group_by includes product, or when no product applies. |
product (anyOf 2) | null | Alternative | |
provider | JSON | Required within parent | |
provider (anyOf 1) | string | Alternative | AI provider. Null unless group_by includes provider. Known values: ANTHROPIC, AWS, AZURE, CURSOR, FIREWORKS, GCP, OPENAI, RAMP Read only: true |
provider (anyOf 2) | null | Alternative | |
usage_date | string | Required within parent | UTC calendar date for this usage row. Format: date |
user_email | JSON | Required within parent | |
user_email (anyOf 1) | string | Alternative | Email of the Ramp user, or the email the provider reported when the usage is not attributed to a Ramp user. Null unless group_by includes user. Format: email |
user_email (anyOf 2) | null | Alternative | |
user_id | JSON | Required within parent | |
user_id (anyOf 1) | string | Alternative | Ramp user. Null unless group_by includes user, or when the usage is not attributed to a Ramp user. Format: uuid |
user_id (anyOf 2) | null | Alternative | |
web_search_requests | JSON | Required within parent | |
web_search_requests (anyOf 1) | integer | Alternative | Number of provider web-search requests. |
web_search_requests (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Referenced models: Fetch a payment — response body — amount
List Ramp users with estimated AI spend during the requested period — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | array | Required within parent | Ramp users and their AI spend. |
data[] | Model | Each item | Expand List Ramp users with estimated AI spend during the requested period — response body — data item |
page | Model | Required within parent | Expand List bills — response body — page Pagination details for this response. |
Referenced models: List bills — response body — page, List Ramp users with estimated AI spend during the requested period — response body — data item
List Ramp users with estimated AI spend during the requested period — response body — data item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
department_name | JSON | Required within parent | |
department_name (anyOf 1) | string | Alternative | Current Ramp department name, when available. |
department_name (anyOf 2) | null | Alternative | |
email | string | Required within parent | Ramp user email. Format: email |
estimated_cost | Model | Required within parent | Expand Fetch a payment — response body — amount Usage-derived estimated cost for the requested period. Read only: true |
estimated_cost_by_provider | array | Required within parent | Estimated cost split by AI provider. |
estimated_cost_by_provider[] | Model | Each item | Expand List Ramp users with estimated AI spend during the requested period — response body — data item estimated cost by provider item |
first_name | string | Required within parent | Ramp user first name. |
id | string | Required within parent | Unique Ramp user identifier. Format: uuid |
is_anomalous | boolean | Required within parent | Whether Ramp detected anomalous AI spend for the user during the requested period. |
is_ramp_user | boolean | Required within parent | Whether the person is a Ramp user. Always true for records returned by this endpoint. |
last_name | string | Required within parent | Ramp user last name. |
user_status | string | Required within parent | Current Ramp user lifecycle status. Known values: active, deleted, draft, inactive, pending Read only: true |
Referenced models: List Ramp users with estimated AI spend during the requested period — response body — data item estimated cost by provider item, Fetch a payment — response body — amount
List Ramp users with estimated AI spend during the requested period — response body — data item estimated cost by provider item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
estimated_cost | Model | Required within parent | Expand Fetch a payment — response body — amount Usage-derived estimated cost for this provider. Read only: true |
provider | string | Required within parent | AI provider attributed to this estimated cost. Known values: ANTHROPIC, CURSOR, FIREWORKS, OPENAI, RAMP Read only: true |
Referenced models: Fetch a payment — response body — amount
List provider API keys and their estimated spend — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | array | Required within parent | Resources returned in this page. |
data[] | Model | Each item | Expand List provider API keys and their estimated spend — response body — data item |
page | Model | Required within parent | Expand List bills — response body — page Pagination details for this response. |
Referenced models: List bills — response body — page, List provider API keys and their estimated spend — response body — data item
List provider API keys and their estimated spend — response body — data / item / active_spend_limit / interval: annual, daily, monthly, quarterly, tertiary, total, weekly, yearly
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
amount | Model | Required within parent | Expand Fetch a payment — response body — amount Maximum spend allowed per reset interval. Read only: true |
interval | string | Required within parent | How often the spend limit resets. Known values: annual, daily, monthly, quarterly, tertiary, total, weekly, yearly Read only: true |
Referenced models: Fetch a payment — response body — amount
List provider API keys and their estimated spend — response body — data item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A provider API key tracked for AI spend. Estimated cost applies to the requested period. All other fields reflect current metadata, not state as of the requested dates. |
active_spend_limit | JSON | Required within parent | |
active_spend_limit (anyOf 1) | Model | Alternative | Expand List provider API keys and their estimated spend — response body — data / item / active_spend_limit / interval: annual, daily, monthly, quarterly, tertiary, total, weekly, yearly Currently active configured spend limit. Its amount and reset cadence are independent of the requested historical dates. Null when the API key has no active spend limit. |
active_spend_limit (anyOf 2) | null | Alternative | |
estimated_cost | Model | Required within parent | Expand Fetch a payment — response body — amount Cost estimated by Ramp for usage attributed to the API key during the requested period. Zero when no usage was attributed. Read only: true |
external_id | string | Required within parent | API key identifier assigned by the provider. |
id | string | Required within parent | Unique identifier of the API key. Format: uuid |
name | JSON | Required within parent | |
name (anyOf 1) | string | Alternative | API key name reported by the provider. |
name (anyOf 2) | null | Alternative | |
owner | JSON | Required within parent | |
owner (anyOf 1) | Model | Alternative | Expand List provider API keys and their estimated spend — response body — data item owner email, first name, id, last name Owner identified by Ramp or the provider. Read only: true |
owner (anyOf 2) | null | Alternative | |
provider | string | Required within parent | Provider that issued the API key. Known values: ANTHROPIC, OPENAI, RAMP Read only: true |
provider_created_at | JSON | Required within parent | |
provider_created_at (anyOf 1) | string | Alternative | Date and time the provider created the API key. Format: date-time |
provider_created_at (anyOf 2) | null | Alternative | |
provider_key_hint | JSON | Required within parent | |
provider_key_hint (anyOf 1) | string | Alternative | Redacted API key hint reported by the provider. |
provider_key_hint (anyOf 2) | null | Alternative | |
provider_last_used_at | JSON | Required within parent | |
provider_last_used_at (anyOf 1) | string | Alternative | Date and time the provider last recorded usage. Format: date-time |
provider_last_used_at (anyOf 2) | null | Alternative | |
status | JSON | Required within parent | |
status (anyOf 1) | string | Alternative | Current API key status, when available from the provider. Known values: active, expired, locked, terminated |
status (anyOf 2) | null | Alternative | |
synced_at | string | Required within parent | Date and time Ramp last synchronized the API key. Format: date-time |
tags | array | Required within parent | Active tags assigned to the API key. |
tags[] | Model | Each item | Expand List provider API keys and their estimated spend — response body — data item tags item |
Referenced models: List provider API keys and their estimated spend — response body — data item owner email, first name, id, last name, List provider API keys and their estimated spend — response body — data item tags item, List provider API keys and their estimated spend — response body — data / item / active_spend_limit / interval: annual, daily, monthly, quarterly, tertiary, total, weekly, yearly, Fetch a payment — response body — amount
List provider API keys and their estimated spend — response body — data item owner email, first name, id, last name
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
email | JSON | Required within parent | |
email (anyOf 1) | string | Alternative | Owner email reported by Ramp or the provider. Format: email Read only: true |
email (anyOf 2) | null | Alternative | |
first_name | JSON | Required within parent | |
first_name (anyOf 1) | string | Alternative | First name of the matched Ramp user. |
first_name (anyOf 2) | null | Alternative | |
id | JSON | Required within parent | |
id (anyOf 1) | string | Alternative | Unique identifier of the matched Ramp user. Format: uuid |
id (anyOf 2) | null | Alternative | |
last_name | JSON | Required within parent | |
last_name (anyOf 1) | string | Alternative | Last name of the matched Ramp user. |
last_name (anyOf 2) | null | Alternative |
List provider API keys and their estimated spend — response body — data item tags item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
key | string | Required within parent | Tag name. |
value | string | Required within parent | Assigned tag value. |
Replace the business's AI spend settings — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
router_tag_keys | array | Required within parent | Router request-tag keys to break down spend by, in addition to the defaults (user, product). Maximum items: 20 |
router_tag_keys[] | string | Each item | Maximum length: 64 Minimum length: 1 Pattern: ^[^:\s]+$ |
Replace the business's AI spend settings — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
router_tag_keys | array | Required within parent | Router request-tag keys to break down spend by, in addition to the defaults (user, product). |
router_tag_keys[] | string | Each item |
Replace the business's Ramp Router semantic tagging settings — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
config | Model | Required within parent | Expand Replace the business's Ramp Router semantic tagging settings — request body — body config The complete tagging configuration. It replaces the current one. |
expected_version | integer | Required within parent | The version from your last read. Use 0 for the first save. Minimum: 0 |
Referenced models: Replace the business's Ramp Router semantic tagging settings — request body — body config
Replace the business's Ramp Router semantic tagging settings — request body — body config
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
exclusions | array | Optional | API keys or users whose requests are not tagged. Each subject may appear once. Maximum items: 1000 |
exclusions[] | Model | Each item | Expand Replace the business's Ramp Router semantic tagging settings — request body — body config exclusions item |
taxonomies | array | Optional | Taxonomies to classify AI requests by. tag_key values must be unique. Maximum items: 5 |
taxonomies[] | Model | Each item | Expand Replace the business's Ramp Router semantic tagging settings — response body — config taxonomies item |
Referenced models: Replace the business's Ramp Router semantic tagging settings — request body — body config exclusions item, Replace the business's Ramp Router semantic tagging settings — response body — config taxonomies item
Replace the business's Ramp Router semantic tagging settings — request body — body config exclusions item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
subject_id | string | Required within parent | For api_key, the external_id of a RAMP API key. For user, the Ramp Router user ID. Maximum length: 128 Minimum length: 1 |
subject_type | string | Required within parent | Kind of subject to exclude from tagging. One of: api_key, user |
tag_keys | array | Optional | Taxonomies the subject is excluded from. Empty excludes it from every taxonomy. |
tag_keys[] | string | Each item |
Replace the business's Ramp Router semantic tagging settings — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
config | Model | Required within parent | Expand Replace the business's Ramp Router semantic tagging settings — response body — config Current tagging configuration. |
version | JSON | Required within parent | |
version (anyOf 1) | integer | Alternative | Increases by 1 each time the settings change; 0 means never saved. Send it as expected_version when updating. |
version (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Referenced models: Replace the business's Ramp Router semantic tagging settings — response body — config
Replace the business's Ramp Router semantic tagging settings — response body — config
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
exclusions | array | Optional | API keys or users whose requests are not tagged. Each subject may appear once. Maximum items: 1000 |
exclusions[] | Model | Each item | Expand Replace the business's Ramp Router semantic tagging settings — response body — config exclusions item |
taxonomies | array | Optional | Taxonomies to classify AI requests by. tag_key values must be unique. Maximum items: 5 |
taxonomies[] | Model | Each item | Expand Replace the business's Ramp Router semantic tagging settings — response body — config taxonomies item |
Referenced models: Replace the business's Ramp Router semantic tagging settings — response body — config taxonomies item, Replace the business's Ramp Router semantic tagging settings — response body — config exclusions item
Replace the business's Ramp Router semantic tagging settings — response body — config exclusions item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
subject_id | string | Required within parent | For api_key, the external_id of a RAMP API key. For user, the Ramp Router user ID. Maximum length: 128 Minimum length: 1 |
subject_type | string | Required within parent | Kind of subject to exclude from tagging. Known values: api_key, user |
tag_keys | array | Optional | Taxonomies the subject is excluded from. Empty excludes it from every taxonomy. |
tag_keys[] | string | Each item |
Replace the business's Ramp Router semantic tagging settings — response body — config taxonomies item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
allow_unclassified | boolean | Optional | Whether a request can be tagged unclassified when no label fits. Default: true |
description | string | Required within parent | What this taxonomy classifies. The characters < and > are removed. Maximum length: 500 Minimum length: 1 |
enabled | boolean | Optional | Whether this taxonomy is applied to requests. Default: true |
labels | array | Required within parent | Labels a request can receive. Label names must be unique, and unclassified is reserved. Maximum items: 50 Minimum items: 2 |
labels[] | Model | Each item | Expand Replace the business's Ramp Router semantic tagging settings — response body — config taxonomies item labels item |
tag_key | string | Required within parent | Taxonomy identifier, such as team or project. 1-64 characters: lowercase letters, digits, underscores, periods, or hyphens, starting with a letter or digit. Pattern: ^[a-z0-9][a-z0-9_.-]{0,63}$ |
Referenced models: Replace the business's Ramp Router semantic tagging settings — response body — config taxonomies item labels item
Replace the business's Ramp Router semantic tagging settings — response body — config taxonomies item labels item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
description | string | Required within parent | When to choose this label. The characters < and > are removed. Maximum length: 300 Minimum length: 1 |
label | string | Required within parent | Label name. 1-64 characters: lowercase letters, digits, underscores, periods, or hyphens, starting with a letter or digit. Pattern: ^[a-z0-9][a-z0-9_.-]{0,63}$ |