Skip to content

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

FieldTypePresenceDescription and constraints
$objectRoot
dataarrayRequired within parentResources returned in this page.
data[]ModelEach itemExpand List AI usage and estimated spend grouped by the requested dimensions — response body — data item
pageModelRequired within parentExpand 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

FieldTypePresenceDescription and constraints
$objectRoot
cached_input_tokensJSONRequired within parent
cached_input_tokens (anyOf 1)integerAlternativeNumber of cached input tokens.
cached_input_tokens (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
department_idJSONRequired within parent
department_id (anyOf 1)stringAlternativeDepartment of the Ramp user. Null unless group_by includes department, or when the user has no department.
Format: uuid
department_id (anyOf 2)nullAlternative
estimated_costJSONRequired within parent
estimated_cost (anyOf 1)ModelAlternativeExpand 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)nullAlternative
input_tokensJSONRequired within parent
input_tokens (anyOf 1)integerAlternativeNumber of input tokens.
input_tokens (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
modelJSONRequired within parent
model (anyOf 1)stringAlternativeProvider model name. Null unless group_by includes model, or when the provider did not report one.
model (anyOf 2)nullAlternative
output_tokensJSONRequired within parent
output_tokens (anyOf 1)integerAlternativeNumber of output tokens.
output_tokens (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
productJSONRequired within parent
product (anyOf 1)stringAlternativeProduct 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)nullAlternative
providerJSONRequired within parent
provider (anyOf 1)stringAlternativeAI provider. Null unless group_by includes provider.
Known values: ANTHROPIC, AWS, AZURE, CURSOR, FIREWORKS, GCP, OPENAI, RAMP
Read only: true
provider (anyOf 2)nullAlternative
usage_datestringRequired within parentUTC calendar date for this usage row.
Format: date
user_emailJSONRequired within parent
user_email (anyOf 1)stringAlternativeEmail 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)nullAlternative
user_idJSONRequired within parent
user_id (anyOf 1)stringAlternativeRamp user. Null unless group_by includes user, or when the usage is not attributed to a Ramp user.
Format: uuid
user_id (anyOf 2)nullAlternative
web_search_requestsJSONRequired within parent
web_search_requests (anyOf 1)integerAlternativeNumber of provider web-search requests.
web_search_requests (anyOf 2)stringAlternativePattern: ^-?[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

FieldTypePresenceDescription and constraints
$objectRoot
dataarrayRequired within parentRamp users and their AI spend.
data[]ModelEach itemExpand List Ramp users with estimated AI spend during the requested period — response body — data item
pageModelRequired within parentExpand 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

FieldTypePresenceDescription and constraints
$objectRoot
department_nameJSONRequired within parent
department_name (anyOf 1)stringAlternativeCurrent Ramp department name, when available.
department_name (anyOf 2)nullAlternative
emailstringRequired within parentRamp user email.
Format: email
estimated_costModelRequired within parentExpand Fetch a payment — response body — amount
Usage-derived estimated cost for the requested period.
Read only: true
estimated_cost_by_providerarrayRequired within parentEstimated cost split by AI provider.
estimated_cost_by_provider[]ModelEach itemExpand List Ramp users with estimated AI spend during the requested period — response body — data item estimated cost by provider item
first_namestringRequired within parentRamp user first name.
idstringRequired within parentUnique Ramp user identifier.
Format: uuid
is_anomalousbooleanRequired within parentWhether Ramp detected anomalous AI spend for the user during the requested period.
is_ramp_userbooleanRequired within parentWhether the person is a Ramp user. Always true for records returned by this endpoint.
last_namestringRequired within parentRamp user last name.
user_statusstringRequired within parentCurrent 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

FieldTypePresenceDescription and constraints
$objectRoot
estimated_costModelRequired within parentExpand Fetch a payment — response body — amount
Usage-derived estimated cost for this provider.
Read only: true
providerstringRequired within parentAI 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

FieldTypePresenceDescription and constraints
$objectRoot
dataarrayRequired within parentResources returned in this page.
data[]ModelEach itemExpand List provider API keys and their estimated spend — response body — data item
pageModelRequired within parentExpand 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

FieldTypePresenceDescription and constraints
$objectRoot
amountModelRequired within parentExpand Fetch a payment — response body — amount
Maximum spend allowed per reset interval.
Read only: true
intervalstringRequired within parentHow 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

FieldTypePresenceDescription and constraints
$objectRootA 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_limitJSONRequired within parent
active_spend_limit (anyOf 1)ModelAlternativeExpand 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)nullAlternative
estimated_costModelRequired within parentExpand 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_idstringRequired within parentAPI key identifier assigned by the provider.
idstringRequired within parentUnique identifier of the API key.
Format: uuid
nameJSONRequired within parent
name (anyOf 1)stringAlternativeAPI key name reported by the provider.
name (anyOf 2)nullAlternative
ownerJSONRequired within parent
owner (anyOf 1)ModelAlternativeExpand 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)nullAlternative
providerstringRequired within parentProvider that issued the API key.
Known values: ANTHROPIC, OPENAI, RAMP
Read only: true
provider_created_atJSONRequired within parent
provider_created_at (anyOf 1)stringAlternativeDate and time the provider created the API key.
Format: date-time
provider_created_at (anyOf 2)nullAlternative
provider_key_hintJSONRequired within parent
provider_key_hint (anyOf 1)stringAlternativeRedacted API key hint reported by the provider.
provider_key_hint (anyOf 2)nullAlternative
provider_last_used_atJSONRequired within parent
provider_last_used_at (anyOf 1)stringAlternativeDate and time the provider last recorded usage.
Format: date-time
provider_last_used_at (anyOf 2)nullAlternative
statusJSONRequired within parent
status (anyOf 1)stringAlternativeCurrent API key status, when available from the provider.
Known values: active, expired, locked, terminated
status (anyOf 2)nullAlternative
synced_atstringRequired within parentDate and time Ramp last synchronized the API key.
Format: date-time
tagsarrayRequired within parentActive tags assigned to the API key.
tags[]ModelEach itemExpand 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

FieldTypePresenceDescription and constraints
$objectRoot
emailJSONRequired within parent
email (anyOf 1)stringAlternativeOwner email reported by Ramp or the provider.
Format: email
Read only: true
email (anyOf 2)nullAlternative
first_nameJSONRequired within parent
first_name (anyOf 1)stringAlternativeFirst name of the matched Ramp user.
first_name (anyOf 2)nullAlternative
idJSONRequired within parent
id (anyOf 1)stringAlternativeUnique identifier of the matched Ramp user.
Format: uuid
id (anyOf 2)nullAlternative
last_nameJSONRequired within parent
last_name (anyOf 1)stringAlternativeLast name of the matched Ramp user.
last_name (anyOf 2)nullAlternative

List provider API keys and their estimated spend — response body — data item tags item

FieldTypePresenceDescription and constraints
$objectRoot
keystringRequired within parentTag name.
valuestringRequired within parentAssigned tag value.

Replace the business's AI spend settings — request body — body

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
router_tag_keysarrayRequired within parentRouter request-tag keys to break down spend by, in addition to the defaults (user, product).
Maximum items: 20
router_tag_keys[]stringEach itemMaximum length: 64
Minimum length: 1
Pattern: ^[^:\s]+$

Replace the business's AI spend settings — response body

FieldTypePresenceDescription and constraints
$objectRoot
router_tag_keysarrayRequired within parentRouter request-tag keys to break down spend by, in addition to the defaults (user, product).
router_tag_keys[]stringEach item

Replace the business's Ramp Router semantic tagging settings — request body — body

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
configModelRequired within parentExpand Replace the business's Ramp Router semantic tagging settings — request body — body config
The complete tagging configuration. It replaces the current one.
expected_versionintegerRequired within parentThe 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

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
exclusionsarrayOptionalAPI keys or users whose requests are not tagged. Each subject may appear once.
Maximum items: 1000
exclusions[]ModelEach itemExpand Replace the business's Ramp Router semantic tagging settings — request body — body config exclusions item
taxonomiesarrayOptionalTaxonomies to classify AI requests by. tag_key values must be unique.
Maximum items: 5
taxonomies[]ModelEach itemExpand 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

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
subject_idstringRequired within parentFor api_key, the external_id of a RAMP API key. For user, the Ramp Router user ID.
Maximum length: 128
Minimum length: 1
subject_typestringRequired within parentKind of subject to exclude from tagging.
One of: api_key, user
tag_keysarrayOptionalTaxonomies the subject is excluded from. Empty excludes it from every taxonomy.
tag_keys[]stringEach item

Replace the business's Ramp Router semantic tagging settings — response body

FieldTypePresenceDescription and constraints
$objectRoot
configModelRequired within parentExpand Replace the business's Ramp Router semantic tagging settings — response body — config
Current tagging configuration.
versionJSONRequired within parent
version (anyOf 1)integerAlternativeIncreases by 1 each time the settings change; 0 means never saved. Send it as expected_version when updating.
version (anyOf 2)stringAlternativePattern: ^-?[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

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
exclusionsarrayOptionalAPI keys or users whose requests are not tagged. Each subject may appear once.
Maximum items: 1000
exclusions[]ModelEach itemExpand Replace the business's Ramp Router semantic tagging settings — response body — config exclusions item
taxonomiesarrayOptionalTaxonomies to classify AI requests by. tag_key values must be unique.
Maximum items: 5
taxonomies[]ModelEach itemExpand 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

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
subject_idstringRequired within parentFor api_key, the external_id of a RAMP API key. For user, the Ramp Router user ID.
Maximum length: 128
Minimum length: 1
subject_typestringRequired within parentKind of subject to exclude from tagging.
Known values: api_key, user
tag_keysarrayOptionalTaxonomies the subject is excluded from. Empty excludes it from every taxonomy.
tag_keys[]stringEach item

Replace the business's Ramp Router semantic tagging settings — response body — config taxonomies item

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
allow_unclassifiedbooleanOptionalWhether a request can be tagged unclassified when no label fits.
Default: true
descriptionstringRequired within parentWhat this taxonomy classifies. The characters < and > are removed.
Maximum length: 500
Minimum length: 1
enabledbooleanOptionalWhether this taxonomy is applied to requests.
Default: true
labelsarrayRequired within parentLabels a request can receive. Label names must be unique, and unclassified is reserved.
Maximum items: 50
Minimum items: 2
labels[]ModelEach itemExpand Replace the business's Ramp Router semantic tagging settings — response body — config taxonomies item labels item
tag_keystringRequired within parentTaxonomy 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

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
descriptionstringRequired within parentWhen to choose this label. The characters < and > are removed.
Maximum length: 300
Minimum length: 1
labelstringRequired within parentLabel 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}$

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.