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.
Call through Alter
Section titled “Call through Alter”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 osfrom alter_sdk import Appfrom 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()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
query | object | Required within parent | Additional keys: not allowed |
query.providers | array | Optional | |
query.providers[] | string | Each item | One of: ANTHROPIC, AWS, AZURE, CURSOR, FIREWORKS, GCP, OPENAI, RAMP |
query.group_by | array | Optional | |
query.group_by[] | string | Each item | One of: department, model, product, provider, user |
query.products | array | Optional | |
query.products[] | string | Each item | Minimum length: 1 |
query.models | array | Optional | |
query.models[] | string | Each item | Minimum length: 1 |
query.to_date | string | Required within parent | Format: date |
query.page_size | integer | Optional | Default: 20 Maximum: 100 Minimum: 2 |
query.start | string | Optional | Minimum length: 1 |
query.from_date | string | Required within parent | Format: date |
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand 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
Schemas
Section titled “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 bills — response body — page
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Pagination details for a Developer API response. |
next | JSON | Required within parent | |
next (anyOf 1) | string | Alternative | the query to get to the next page; it is in the format of <BASE_URL>?<new_params> |
next (anyOf 2) | null | Alternative |
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
Fetch a payment — response body — amount
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
currency | string | Required within parent | The 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 |
value | JSON | Required within parent | |
value (anyOf 1) | integer | Alternative | The non-negative amount in the smallest denomination of the currency (e.g. cents for USD). Minimum: 0 |
value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Policy, approvals and errors
Section titled “Policy, approvals and errors”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"]