Skip to content

Ramp: List AI usage and estimated spend grouped by the requested dimensions

Ramp aiSpend.getAiSpendUsageListResource: arguments, response, policy and SDK examples.

← AI spend operations · Get started

Operation ramp.get_ai_spend_usage_list_resource

Provider route: GET /developer/v1/ai-spend/usage. Alter supplies the connection’s credentials and routing.

Install @alter-ai/sdk @alter-ai/ramp with npm, or alter-sdk-ramp with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { RampIntegration } from "@alter-ai/ramp";
async function execute(input: Parameters<RampIntegration["aiSpend"]["getAiSpendUsageListResource"]>[0]) {
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
const provider = new RampIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
const call = await provider.aiSpend.getAiSpendUsageListResource(input);
const result = await call.wait();
return result.bodyJson();
} finally {
await app.close();
}
}
import os
from alter_sdk import App
from alter_sdk_ramp import RampIntegration
async def execute(arguments):
async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
provider = RampIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
call = await provider.ai_spend.get_ai_spend_usage_list_resource(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
queryobjectRequired within parentAdditional keys: not allowed
query.providersarrayOptional
query.providers[]stringEach itemOne of: ANTHROPIC, AWS, AZURE, CURSOR, FIREWORKS, GCP, OPENAI, RAMP
query.group_byarrayOptional
query.group_by[]stringEach itemOne of: department, model, product, provider, user
query.productsarrayOptional
query.products[]stringEach itemMinimum length: 1
query.modelsarrayOptional
query.models[]stringEach itemMinimum length: 1
query.to_datestringRequired within parentFormat: date
query.page_sizeintegerOptionalDefault: 20
Maximum: 100
Minimum: 2
query.startstringOptionalMinimum length: 1
query.from_datestringRequired within parentFormat: date

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$ModelRootExpand List AI usage and estimated spend grouped by the requested dimensions — response body

Referenced models: List AI usage and estimated spend grouped by the requested dimensions — response body

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 bills — response body — page
FieldTypePresenceDescription and constraints
$objectRootPagination details for a Developer API response.
nextJSONRequired within parent
next (anyOf 1)stringAlternativethe query to get to the next page; it is in the format of <BASE_URL>?<new_params>
next (anyOf 2)nullAlternative
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

Fetch a payment — response body — amount
FieldTypePresenceDescription and constraints
$objectRoot
currencystringRequired within parentThe currency of the amount in ISO 4217 format (e.g. USD).
Known values: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNH, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, EURC, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, OPEN_USD, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USDB, USDC, USDG, USDT, USN, UYI, UYU, UYW, UZS, VED, VES, VND, VUV, WST, XAD, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XCG, XDR, XOF, XPD, XPF, XPT, XSU, XTS, XUA, XXX, YER, ZAR, ZMW, ZWG, ZWL
valueJSONRequired within parent
value (anyOf 1)integerAlternativeThe non-negative amount in the smallest denomination of the currency (e.g. cents for USD).
Minimum: 0
value (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

SDK function policy ID: ramp.get_ai_spend_usage_list_resource. Catalog operation: get_ai_spend_usage_list_resource. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["ai_spend:read"]

Official provider source

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.