> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vantage.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Vantage API Reference
> Complete reference of all Vantage API endpoints. This page is auto-generated from the OpenAPI specification.
This page is auto-generated from the [OpenAPI specification](https://api.vantage.sh/v2/oas_v3.json).
For interactive testing and detailed schemas, visit the individual endpoint pages linked below.
## AccessGrants
### GET /access\_grants
**Get all access grants**
Return all Access Grants that the current API token has access to.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/accessgrants/get-all-access-grants](https://docs.vantage.sh/api/accessgrants/get-all-access-grants)
***
### POST /access\_grants
**Create access grant**
Create an Access Grant.
#### Request Body
```json theme={null}
{
"resource_token": string // required // The token of the resource for which you are granting access,
"team_token": string // required // The token of the Team you want to grant access to,
"access": string // The access level you want to grant. Defaults to 'allowed'. Allowed values: `denied`, `allowed`
}
```
#### Responses
**201**: Created
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**406**: NotAcceptable
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/accessgrants/create-access-grant](https://docs.vantage.sh/api/accessgrants/create-access-grant)
***
### DELETE /access\_grants/{access_grant_token}
**Delete access grant**
Delete an Access Grant.
#### Path Parameters
* **access\_grant\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/accessgrants/delete-access-grant](https://docs.vantage.sh/api/accessgrants/delete-access-grant)
***
### GET /access\_grants/{access_grant_token}
**Get access grant by token**
Return a specific Access Grant.
#### Path Parameters
* **access\_grant\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/accessgrants/get-access-grant-by-token](https://docs.vantage.sh/api/accessgrants/get-access-grant-by-token)
***
### PUT /access\_grants/{access_grant_token}
**Update access grant**
Update an AccessGrant.
#### Path Parameters
* **access\_grant\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"access": string // required // Allowed or denied access to resource. Allowed values: `denied`, `allowed`
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/accessgrants/update-access-grant](https://docs.vantage.sh/api/accessgrants/update-access-grant)
***
## AccessPolicies
### GET /access\_policies
**Get all access policies**
Return all Access Policies for the current account.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
#### Responses
**200**: OK
**403**: Forbidden
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/accesspolicies/get-all-access-policies](https://docs.vantage.sh/api/accesspolicies/get-all-access-policies)
***
### POST /access\_policies
**Create access policy**
Create an Access Policy. Requires a personal API token belonging to a user with the Owner role and the write scope.
#### Request Body
```json theme={null}
{
"title": string // required // The title of the AccessPolicy,
"policy": { // required // The AccessPolicy definition as a v1 document with vantage.* VQL
"api_version": string // required // The AccessPolicy document version. Allowed values: `v1`,
"policy": { // required // The AccessPolicy rules for this version
"filter": string // required // Vantage Query Language (VQL) that controls which costs this AccessPolicy allows
}
},
"description": string // The description of the AccessPolicy,
"team_tokens": [string] // The tokens for Teams this AccessPolicy is assigned to
}
```
#### Responses
**201**: Created
**400**: BadRequest
**403**: Forbidden
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/accesspolicies/create-access-policy](https://docs.vantage.sh/api/accesspolicies/create-access-policy)
***
### DELETE /access\_policies/{access_policy_token}
**Delete access policy**
Delete an Access Policy. Requires a personal API token belonging to a user with the Owner role and the write scope.
#### Path Parameters
* **access\_policy\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**403**: Forbidden
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/accesspolicies/delete-access-policy](https://docs.vantage.sh/api/accesspolicies/delete-access-policy)
***
### PUT /access\_policies/{access_policy_token}
**Update access policy**
Update an Access Policy. Requires a personal API token belonging to a user with the Owner role and the write scope.
#### Path Parameters
* **access\_policy\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the AccessPolicy,
"policy": { // The AccessPolicy definition as a v1 document with vantage.* VQL
"api_version": string // required // The AccessPolicy document version. Allowed values: `v1`,
"policy": { // required // The AccessPolicy rules for this version
"filter": string // required // Vantage Query Language (VQL) that controls which costs this AccessPolicy allows
}
},
"description": string // The description of the AccessPolicy,
"team_tokens": [string] // The tokens for Teams this AccessPolicy is assigned to
}
```
#### Responses
**200**: OK
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/accesspolicies/update-access-policy](https://docs.vantage.sh/api/accesspolicies/update-access-policy)
***
## Annotations
### GET /annotations
**Get all annotations**
Return all Annotations.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The number of results to return. The maximum is 5000.
* **report\_token** (string) - Optional: Filter by Report token.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/annotations/get-all-annotations](https://docs.vantage.sh/api/annotations/get-all-annotations)
***
### POST /annotations
**Create an annotation**
Create an Annotation.
#### Request Body
```json theme={null}
{
"report_tokens": [string] // required // The tokens of the Reports to annotate,
"title": string // The title of the Annotation. Defaults to a title generated from the first Report and date,
"date": string // required // The date of the Annotation. ISO 8601 formatted,
"message": string // required // The message of the Annotation
}
```
#### Responses
**201**: Annotation created successfully.
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/annotations/create-an-annotation](https://docs.vantage.sh/api/annotations/create-an-annotation)
***
### DELETE /annotations/{annotation_token}
**Delete an annotation**
Delete an Annotation.
#### Path Parameters
* **annotation\_token** (path) (string) - **Required**: The token of the Annotation.
#### Responses
**204**: Annotation deleted successfully.
**403**: Forbidden
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/annotations/delete-an-annotation](https://docs.vantage.sh/api/annotations/delete-an-annotation)
***
### PUT /annotations/{annotation_token}
**Update an annotation**
Update an Annotation.
#### Path Parameters
* **annotation\_token** (path) (string) - **Required**: The token of the Annotation.
#### Request Body
```json theme={null}
{
"title": string // The title of the Annotation,
"date": string // The date of the Annotation. ISO 8601 formatted,
"message": string // The message of the Annotation,
"report_tokens": [string] // The tokens of the Reports to associate with the Annotation
}
```
#### Responses
**200**: Annotation updated successfully.
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/annotations/update-an-annotation](https://docs.vantage.sh/api/annotations/update-an-annotation)
***
## AnomalyAlerts
### GET /anomaly\_alerts
**Get all anomaly alerts**
Return all Anomaly Alerts that the current API token has access to.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **start\_date** (string (date-time)) - Optional: The start date of the anomalies to return. ISO 8601 formatted.
* **end\_date** (string (date-time)) - Optional: The end date of the anomalies to return. ISO 8601 formatted.
* **provider** (string) - Optional: The provider of the anomalies to return.
* **service** (string) - Optional: The service of the anomalies to return.
* **cost\_category** (string) - Optional: The cost category of the anomalies to return.
* **cost\_report\_token** (string) - Optional: The cost report token of the anomalies to return.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/anomalyalerts/get-all-anomaly-alerts](https://docs.vantage.sh/api/anomalyalerts/get-all-anomaly-alerts)
***
### GET /anomaly\_alerts/{anomaly_alert_token}
**Get anomaly alert by token**
Return an AnomalyAlert that the current API token has access to.
#### Path Parameters
* **anomaly\_alert\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/anomalyalerts/get-anomaly-alert-by-token](https://docs.vantage.sh/api/anomalyalerts/get-anomaly-alert-by-token)
***
### PUT /anomaly\_alerts/{anomaly_alert_token}
**Update anomaly alert**
Update an AnomalyAlert.
#### Path Parameters
* **anomaly\_alert\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"status": string // required // The status of the Anomaly Alert,
"feedback": string // Optional additional comments for why this alert is ignored
}
```
#### Responses
**200**: OK
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/anomalyalerts/update-anomaly-alert](https://docs.vantage.sh/api/anomalyalerts/update-anomaly-alert)
***
## AnomalyNotifications
### GET /anomaly\_notifications
**Get all anomaly notifications**
Return all Anomaly Notifications.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **workspace\_token** (string) - Optional: Filter by workspace token.
* **cost\_report\_token** (string) - Optional: Filter by Cost Report token.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/anomalynotifications/get-all-anomaly-notifications](https://docs.vantage.sh/api/anomalynotifications/get-all-anomaly-notifications)
***
### POST /anomaly\_notifications
**Create anomaly notification**
Create an Anomaly Notification for a Cost Report.
#### Request Body
```json theme={null}
{
"cost_report_token": string // required // The token of the Cost Report that has the notification,
"threshold": integer // The threshold amount that must be met for the notification to fire,
"user_tokens": [string] // The tokens of the Users that receive the notification,
"recipient_emails": [string] // Email addresses that receive the notification. Must be organization users, on the account's SSO domain, or an approved third-party service address,
"recipient_channels": [string] // The Slack/MS Teams channels that receive the notification
}
```
#### Responses
**201**: Created
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/anomalynotifications/create-anomaly-notification](https://docs.vantage.sh/api/anomalynotifications/create-anomaly-notification)
***
### DELETE /anomaly\_notifications/{anomaly_notification_token}
**Delete anomaly notification**
Delete an Anomaly Notification.
#### Path Parameters
* **anomaly\_notification\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/anomalynotifications/delete-anomaly-notification](https://docs.vantage.sh/api/anomalynotifications/delete-anomaly-notification)
***
### GET /anomaly\_notifications/{anomaly_notification_token}
**Get anomaly notification by token**
Return an Anomaly Notification that the current API token has access to.
#### Path Parameters
* **anomaly\_notification\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/anomalynotifications/get-anomaly-notification-by-token](https://docs.vantage.sh/api/anomalynotifications/get-anomaly-notification-by-token)
***
### PUT /anomaly\_notifications/{anomaly_notification_token}
**Update anomaly notification**
Update an Anomaly Notification.
#### Path Parameters
* **anomaly\_notification\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"threshold": integer // The threshold amount that must be met for the notification to fire,
"user_tokens": [string] // The tokens of the users that receive the notification,
"recipient_emails": [string] // Email addresses that receive the notification. Must be organization users, on the account's SSO domain, or an approved third-party service address,
"recipient_channels": [string] // The Slack/MS Teams channels that receive the notification
}
```
#### Responses
**200**: OK
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/anomalynotifications/update-anomaly-notification](https://docs.vantage.sh/api/anomalynotifications/update-anomaly-notification)
***
## AuditLogs
### GET /audit\_logs
**Get all audit logs**
Return all AuditLogs.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. Defaults to 100. The maximum is 5000.
* **user** (integer (int32)) - Optional: Filter by personal or service API token that performed the action.
* **workspace\_token** (string) - Optional: Filter by workspace token.
* **action** (string) - Optional: Filter by action type.
* Allowed values: `create`, `update`, `delete`
* **object\_name** (string) - Optional: Filter by object name.
* **source** (string) - Optional: Filter by source.
* Allowed values: `console`, `api`, `finops_agent`
* **object\_type** (string) - Optional: Filter by object type.
* Allowed values: `virtual_tag`, `cost_report`, `recommendation_commitment`, `segment`, `access_policy`
* **token** (string) - Optional: Filter by audit log token.
* **object\_token** (string) - Optional: Filter by object token (auditable\_token).
* **start\_date** (string (date)) - Optional: Filter by start date (ISO 8601 format, e.g., 2024-06-01).
* **end\_date** (string (date)) - Optional: Filter by end date (ISO 8601 format, e.g., 2024-06-01).
#### Responses
**200**: OK
**403**: Forbidden
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/auditlogs/get-all-audit-logs](https://docs.vantage.sh/api/auditlogs/get-all-audit-logs)
***
### GET /audit\_logs/{audit_log_token}
**Get audit log by token**
Return a specific AuditLog.
#### Path Parameters
* **audit\_log\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**403**: Forbidden
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/auditlogs/get-audit-log-by-token](https://docs.vantage.sh/api/auditlogs/get-audit-log-by-token)
***
## BillingProfiles
### GET /billing\_profiles
**Get all billing profiles**
Returns a list of billing profiles (MSP invoicing required).
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/billingprofiles/get-all-billing-profiles](https://docs.vantage.sh/api/billingprofiles/get-all-billing-profiles)
***
### POST /billing\_profiles
**Create billing profile**
Create a billing profile (MSP invoicing required).
#### Request Body
```json theme={null}
{
"nickname": string // required // Display name for the billing profile,
"billing_information_attributes": { // Billing address and contact information
"token": string,
"company_name": string // Company name for billing,
"country_code": string // ISO country code,
"address_line_1": string // First line of billing address,
"address_line_2": string // Second line of billing address,
"city": string // City for billing address,
"state": string // State or province for billing address,
"postal_code": string // Postal or ZIP code,
"billing_email": [string] // Array of billing email addresses
},
"business_information_attributes": { // Business information and custom fields
"token": string,
"metadata": { // Business metadata including custom fields
"custom_fields": [ // Array of custom field objects
{
"name": string // Custom field name,
"value": string // Custom field value
}
]
}
},
"banking_information_attributes": { // Banking details (MSP accounts only)
"token": string,
"bank_name": string // Name of the bank,
"beneficiary_name": string // Name of the account beneficiary,
"tax_id": string // Tax identification number,
"secure_data": { // Encrypted banking details
"account_number": string // Bank account number (US),
"routing_number": string // Bank routing number (US),
"iban": string // International Bank Account Number (EU),
"swift_bic": string // SWIFT/BIC code (EU)
}
},
"invoice_adjustment_attributes": { // Invoice adjustments (taxes, fees, etc.)
"token": string,
"adjustment_items": [ // Array of adjustment items
{
"name": string // required // Name of the adjustment,
"adjustment_type": string // Type of adjustment. Allowed values: `charge`, `credit`, `discount`,
"calculation_type": string // required // How the adjustment is calculated. Allowed values: `fixed`, `percentage`,
"amount": number // required // Amount or percentage value
}
]
}
}
```
#### Responses
**201**: Created
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/billingprofiles/create-billing-profile](https://docs.vantage.sh/api/billingprofiles/create-billing-profile)
***
### DELETE /billing\_profiles/{billing_profile_token}
**Delete billing profile**
Requires MSP invoicing to be enabled on the account.
#### Path Parameters
* **billing\_profile\_token** (path) (string) - **Required**
#### Responses
**204**: Billing Profile deleted successfully.
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/billingprofiles/delete-billing-profile](https://docs.vantage.sh/api/billingprofiles/delete-billing-profile)
***
### GET /billing\_profiles/{billing_profile_token}
**Get billing profile by token**
Requires MSP invoicing to be enabled on the account.
#### Path Parameters
* **billing\_profile\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/billingprofiles/get-billing-profile-by-token](https://docs.vantage.sh/api/billingprofiles/get-billing-profile-by-token)
***
### PUT /billing\_profiles/{billing_profile_token}
**Update billing profile**
Requires MSP invoicing to be enabled on the account.
#### Path Parameters
* **billing\_profile\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"nickname": string // Display name for the billing profile,
"billing_information_attributes": { // Billing address and contact information
"token": string,
"company_name": string // Company name for billing,
"country_code": string // ISO country code,
"address_line_1": string // First line of billing address,
"address_line_2": string // Second line of billing address,
"city": string // City for billing address,
"state": string // State or province for billing address,
"postal_code": string // Postal or ZIP code,
"billing_email": [string] // Array of billing email addresses
},
"business_information_attributes": { // Business information and custom fields
"token": string,
"metadata": { // Business metadata including custom fields
"custom_fields": [ // Array of custom field objects
{
"name": string // Custom field name,
"value": string // Custom field value
}
]
}
},
"banking_information_attributes": { // Banking details (MSP accounts only)
"token": string,
"bank_name": string // Name of the bank,
"beneficiary_name": string // Name of the account beneficiary,
"tax_id": string // Tax identification number,
"secure_data": { // Encrypted banking details
"account_number": string // Bank account number (US),
"routing_number": string // Bank routing number (US),
"iban": string // International Bank Account Number (EU),
"swift_bic": string // SWIFT/BIC code (EU)
}
},
"invoice_adjustment_attributes": { // Invoice adjustments (taxes, fees, etc.)
"token": string,
"adjustment_items": [ // Array of adjustment items
{
"name": string // required // Name of the adjustment,
"adjustment_type": string // Type of adjustment. Allowed values: `charge`, `credit`, `discount`,
"calculation_type": string // required // How the adjustment is calculated. Allowed values: `fixed`, `percentage`,
"amount": number // required // Amount or percentage value
}
]
}
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/billingprofiles/update-billing-profile](https://docs.vantage.sh/api/billingprofiles/update-billing-profile)
***
## BillingRules
### GET /billing\_rules
**Get all billing rules**
Returns a list of billing rules.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/billingrules/get-all-billing-rules](https://docs.vantage.sh/api/billingrules/get-all-billing-rules)
***
### POST /billing\_rules
**Create billing rule**
Create a BillingRule.
#### Request Body
```json theme={null}
{
"type": string // required // The type of the BillingRule. Note: the values are case insensitive. Allowed values: `exclusion`, `adjustment`, `credit`, `charge`, `custom`,
"title": string // required // The title of the BillingRule,
"start_period": string // The start period of the BillingRule. DEPRECATED: use start_date instead,
"start_date": string // The start date of the BillingRule. ISO 8601 formatted,
"end_date": string // The end date of the BillingRule. ISO 8601 formatted,
"apply_to_all": boolean // Determines if the BillingRule applies to all current and future managed accounts,
"charge_type": string // The charge type of the BillingRule. Required for Exclusion rules,
"percentage": number // The percentage of the cost shown. Required for Adjustment rules. Example value: 75.0,
"service": string // The service of the BillingRule. Required for Charge and Credit rules,
"category": string // The category of the BillingRule. Required for Charge and Credit rules,
"sub_category": string // The subcategory of the BillingRule. Required for Charge and Credit rules,
"amount": number // The amount for the BillingRule. Required for Charge and Credit rules. Example value: 300,
"sql_query": string // The SQL query for the BillingRule. Required for Custom rules. Example value: UPDATE costs SET costs.amount = costs.amount * 0.95
}
```
#### Responses
**201**: Created
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/billingrules/create-billing-rule](https://docs.vantage.sh/api/billingrules/create-billing-rule)
***
### DELETE /billing\_rules/{billing_rule_token}
**Delete billing rule**
Delete a BillingRule.
#### Path Parameters
* **billing\_rule\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/billingrules/delete-billing-rule](https://docs.vantage.sh/api/billingrules/delete-billing-rule)
***
### GET /billing\_rules/{billing_rule_token}
**Get billing rule by token**
Return a BillingRule.
#### Path Parameters
* **billing\_rule\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/billingrules/get-billing-rule-by-token](https://docs.vantage.sh/api/billingrules/get-billing-rule-by-token)
***
### PUT /billing\_rules/{billing_rule_token}
**Update billing rule**
Update a BillingRule.
#### Path Parameters
* **billing\_rule\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the BillingRule,
"charge_type": string // The charge type of the BillingRule,
"percentage": number // The percentage of the cost shown. Example value: 75.0,
"service": string // The service of the BillingRule,
"category": string // The category of the BillingRule,
"sub_category": string // The subcategory of the BillingRule,
"start_period": string // The start period of the BillingRule,
"amount": number // The credit amount for the BillingRule. Example value: 300,
"start_date": string // The start date of the BillingRule. ISO 8601 formatted,
"end_date": string // The end date of the BillingRule. ISO 8601 formatted,
"apply_to_all": boolean // Determines if the BillingRule applies to all current and future managed accounts,
"sql_query": string // The SQL query of the BillingRule
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/billingrules/update-billing-rule](https://docs.vantage.sh/api/billingrules/update-billing-rule)
***
## BudgetAlerts
### GET /budget\_alerts
**Get all budget alerts**
Return all BudgetAlerts.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The number of results to return. The maximum is 1000.
* **workspace\_token** (string) - Optional: Filter by workspace token.
* **budget\_token** (string) - Optional: Filter by budget token.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/budgetalerts/get-all-budget-alerts](https://docs.vantage.sh/api/budgetalerts/get-all-budget-alerts)
***
### POST /budget\_alerts
**Create budget alert**
Create a Budget Alert.
#### Request Body
```json theme={null}
{
"budget_tokens": [string] // required // The tokens of the Budget that has the alert,
"threshold": integer // required // The threshold amount that must be met for the alert to fire,
"workspace_token": string // The token of the Workspace to add the BudgetAlert to. Required if the API token is associated with multiple Workspaces,
"user_tokens": [string] // The tokens of the users that receive the alert,
"recipient_emails": [string] // Email addresses that receive the alert. Must be organization users, on the account's SSO domain, or an approved third-party service address,
"duration_in_days": string // required // The number of days from the start or end of the month to trigger the alert if the threshold is reached. For the full month, pass an empty value,
"period_to_track": string // The period tracked on the alert. Used with duration_in_days to determine the time window of the alert. Defaults to start_of_the_month if not passed. Possible values: start_of_the_month, end_of_the_month,
"recipient_channels": [string] // The channels receiving the alerts. Requires an integration provider to be connected
}
```
#### Responses
**201**: Created
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/budgetalerts/create-budget-alert](https://docs.vantage.sh/api/budgetalerts/create-budget-alert)
***
### DELETE /budget\_alerts/{budget_alert_token}
**Delete budget alert**
Delete a BudgetAlert.
#### Path Parameters
* **budget\_alert\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/budgetalerts/delete-budget-alert](https://docs.vantage.sh/api/budgetalerts/delete-budget-alert)
***
### GET /budget\_alerts/{budget_alert_token}
**Get budget alert by token**
Return a BudgetAlert.
#### Path Parameters
* **budget\_alert\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/budgetalerts/get-budget-alert-by-token](https://docs.vantage.sh/api/budgetalerts/get-budget-alert-by-token)
***
### PUT /budget\_alerts/{budget_alert_token}
**Update budget alert**
Updates an existing BudgetAlert.
#### Path Parameters
* **budget\_alert\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"budget_tokens": [string] // The tokens of the Budget that has the alert,
"threshold": integer // The threshold amount that must be met for the alert to fire,
"workspace_token": string // The token of the Workspace the BudgetAlert belongs to. Required if the API token is associated with multiple Workspaces,
"user_tokens": [string] // The tokens of the users that receive the alert,
"recipient_emails": [string] // Email addresses that receive the alert. Must be organization users, on the account's SSO domain, or an approved third-party service address,
"duration_in_days": string // The number of days from the start or end of the month to trigger the alert if the threshold is reached. For the full month, pass an empty value,
"period_to_track": string // The period tracked on the alert. Used with duration_in_days to determine the time window of the alert. Defaults to start_of_the_month if not passed. Possible values: start_of_the_month, end_of_the_month,
"recipient_channels": [string] // The channels receiving the alerts. Requires an integration provider to be connected
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/budgetalerts/update-budget-alert](https://docs.vantage.sh/api/budgetalerts/update-budget-alert)
***
## Budgets
### GET /budgets
**Get all budgets**
Return all Budgets.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The number of results to return. The maximum is 1000.
* **q** (string) - Optional: Search budgets by name.
* **workspace\_token** (string) - Optional: The workspace token of the budgets to return.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/budgets/get-all-budgets](https://docs.vantage.sh/api/budgets/get-all-budgets)
***
### POST /budgets
**Create budget**
Create a Budget.
#### Request Body
```json theme={null}
{
"name": string // required // The name of the Budget,
"workspace_token": string // The token of the Workspace to add the Budget to,
"cost_report_token": string // The CostReport token. Ignored for hierarchical Budgets,
"type": string // The type of Budget. One of: cost, usage. Allowed values: `cost`, `usage`,
"unit": string // The usage unit for usage Budgets,
"child_budget_tokens": [string] // The tokens of any child Budgets when creating a hierarchical Budget. Child budgets must share the same current period dates,
"period_cadence": { // The interval cadence for budget periods
"starts_at": string // required // The anchor date for budget period intervals. Send null to clear,
"interval_count": integer // The number of interval units per budget period,
"interval_unit": string // The unit for budget period intervals. One of: day, week, month, year. Allowed values: `day`, `week`, `month`, `year`
},
"periods": [ // The periods for the Budget. The start_at and end_at must be iso8601 formatted e.g. YYYY-MM-DD. Ignored for hierarchical Budgets
{
"start_at": string // required // The start date of the period,
"end_at": string // The end date of the period,
"amount": number // required // The amount of the period
}
]
}
```
#### Responses
**201**: Created
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/budgets/create-budget](https://docs.vantage.sh/api/budgets/create-budget)
***
### DELETE /budgets/{budget_token}
**Delete budget**
Delete a Budget.
#### Path Parameters
* **budget\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/budgets/delete-budget](https://docs.vantage.sh/api/budgets/delete-budget)
***
### GET /budgets/{budget_token}
**Get budget by token**
Return a Budget.
#### Path Parameters
* **budget\_token** (path) (string) - **Required**
#### Query Parameters
* **include\_performance** (boolean) - Optional: Include performance data.
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/budgets/get-budget-by-token](https://docs.vantage.sh/api/budgets/get-budget-by-token)
***
### PUT /budgets/{budget_token}
**Update budget**
Update a Budget.
#### Path Parameters
* **budget\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"name": string // The name of the Budget,
"cost_report_token": string // The CostReport token. Ignored for hierarchical Budgets,
"type": string // The type of Budget. One of: cost, usage. Allowed values: `cost`, `usage`,
"unit": string // The usage unit for usage Budgets. Send null to clear,
"child_budget_tokens": [string] // The tokens of any child Budgets when creating a hierarchical Budget. Child budgets must share the same current period dates. Omitted on update to leave the current child list unchanged,
"period_cadence": { // The interval cadence for budget periods. Changing cadence after creation is rejected
"starts_at": string // required // The anchor date for budget period intervals. Send null to clear,
"interval_count": integer // The number of interval units per budget period,
"interval_unit": string // The unit for budget period intervals. One of: day, week, month, year. Allowed values: `day`, `week`, `month`, `year`
},
"periods": [ // The periods for the Budget. The start_at and end_at must be iso8601 formatted e.g. YYYY-MM-DD. Ignored for hierarchical Budgets
{
"start_at": string // required // The start date of the period,
"end_at": string // The end date of the period,
"amount": number // required // The amount of the period
}
]
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/budgets/update-budget](https://docs.vantage.sh/api/budgets/update-budget)
***
## BusinessMetrics
### GET /business\_metrics
**Get all business metrics**
Return all BusinessMetrics that the current API token has access to.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 5000.
* **q** (string) - Optional: Search business metrics by title.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/businessmetrics/get-all-business-metrics](https://docs.vantage.sh/api/businessmetrics/get-all-business-metrics)
***
### POST /business\_metrics
**Create business metric**
Create a new BusinessMetric.
#### Request Body
```json theme={null}
{
"title": string // required // The title of the BusinessMetrics,
"cost_report_tokens_with_metadata": [ // The tokens for any CostReports that use the BusinessMetric, the unit scale, and label filter
{
"cost_report_token": string // required // The token of the CostReport the BusinessMetric is attached to,
"unit_scale": string // Determines the scale of the BusinessMetric's values within the CostReport. Allowed values: `per_unit`, `per_hundred`, `per_thousand`, `per_million`, `per_billion`,
"calculation_type": string // The calculation type applied when this BusinessMetric is used in the CostReport. Allowed values: `unit_cost`, `gross_margin`, `usage_unit_cost`, `raw_business_metric`,
"label": string // Optional custom display name for this BusinessMetric on the CostReport. When omitted, a default is derived from the calculation type,
"label_filter": [string] // Include only values with these labels in the CostReport,
"label_filters": object // Include only ClickHouse BusinessMetric values matching every label key and one of its values
}
],
"values": [ // The dates, amounts, and (optional) labels for the BusinessMetric
{
"date": string // required,
"amount": number // required,
"label": string
}
],
"forecasted_values": [ // The dates, amounts, and (optional) labels for forecasted BusinessMetric values
{
"date": string // required,
"amount": number // required,
"label": string
}
],
"datadog_metric_fields": { // Datadog metric configuration fields
"integration_token": string // Integration token for the account from which you would like to fetch metrics,
"query": string // Datadog metrics query string. e.g. sum:aws.applicationelb.request_count{region:us-east-1}.rollup(avg,daily)
},
"cloudwatch_fields": { // Cloudwatch configuration fields
"integration_token": string // Integration token for the account from which you would like to fetch metrics,
"stat": string,
"region": string,
"namespace": string,
"metric_name": string,
"label_dimension": string,
"dimensions": [
{
"name": string,
"value": string
}
]
},
"gcp_bigquery_metric_fields": { // GCP BigQuery metric configuration fields
"integration_token": string // Integration token for the GCP integration from which you would like to fetch metrics,
"query_project_id": string // GCP project in which the BigQuery job should run,
"sql_query": string // BigQuery SQL query returning date, value, and optional label columns
},
"snowflake_metric_fields": { // Snowflake metric configuration fields
"integration_token": string // Integration token for the Snowflake integration from which you would like to fetch metrics,
"sql_query": string // Snowflake SQL query returning date, value, and optional label columns
},
"clickhouse_metric_fields": { // ClickHouse metric configuration fields
"integration_token": string // Integration token for the ClickHouse integration from which you would like to fetch metrics,
"query_endpoint_id": string // UUID of the ClickHouse query endpoint used to fetch metrics
}
}
```
#### Responses
**201**: Created
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/businessmetrics/create-business-metric](https://docs.vantage.sh/api/businessmetrics/create-business-metric)
***
### DELETE /business\_metrics/{business_metric_token}
**Delete business metric**
Deletes an existing BusinessMetric.
#### Path Parameters
* **business\_metric\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**403**: Forbidden
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/businessmetrics/delete-business-metric](https://docs.vantage.sh/api/businessmetrics/delete-business-metric)
***
### GET /business\_metrics/{business_metric_token}
**Get business metric by token**
Return a BusinessMetric.
#### Path Parameters
* **business\_metric\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/businessmetrics/get-business-metric-by-token](https://docs.vantage.sh/api/businessmetrics/get-business-metric-by-token)
***
### PUT /business\_metrics/{business_metric_token}
**Update business metric**
Updates an existing BusinessMetric.
#### Path Parameters
* **business\_metric\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the BusinessMetric,
"cost_report_tokens_with_metadata": [ // The tokens for any CostReports that use the BusinessMetric, and the unit scale
{
"cost_report_token": string // required // The token of the CostReport the BusinessMetric is attached to,
"unit_scale": string // Determines the scale of the BusinessMetric's values within the CostReport. Allowed values: `per_unit`, `per_hundred`, `per_thousand`, `per_million`, `per_billion`,
"calculation_type": string // The calculation type applied when this BusinessMetric is used in the CostReport. Allowed values: `unit_cost`, `gross_margin`, `usage_unit_cost`, `raw_business_metric`,
"label": string // Optional custom display name for this BusinessMetric on the CostReport. When omitted, a default is derived from the calculation type,
"label_filter": [string] // Include only values with these labels in the CostReport,
"label_filters": object // Include only ClickHouse BusinessMetric values matching every label key and one of its values
}
],
"values": [ // The dates, amounts, and (optional) labels for the BusinessMetric
{
"date": string // required,
"amount": number // required,
"label": string
}
],
"forecasted_values": [ // The dates, amounts, and (optional) labels for forecasted BusinessMetric values
{
"date": string // required,
"amount": number // required,
"label": string
}
],
"datadog_metric_fields": { // Datadog metric configuration fields
"integration_token": string // Integration token for the account from which you would like to fetch metrics,
"query": string // Datadog metrics query string. e.g. sum:aws.applicationelb.request_count{region:us-east-1}.rollup(avg,daily)
},
"cloudwatch_fields": { // Cloudwatch configuration fields
"integration_token": string // Integration token for the account from which you would like to fetch metrics,
"stat": string,
"region": string,
"namespace": string,
"metric_name": string,
"label_dimension": string,
"dimensions": [
{
"name": string,
"value": string
}
]
},
"snowflake_metric_fields": { // Snowflake metric configuration fields
"integration_token": string // Integration token for the Snowflake integration from which you would like to fetch metrics,
"sql_query": string // Snowflake SQL query returning date, value, and optional label columns
}
}
```
#### Responses
**200**: OK
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/businessmetrics/update-business-metric](https://docs.vantage.sh/api/businessmetrics/update-business-metric)
***
### GET /business\_metrics/{business_metric_token}/forecasted\_values
**Get business metric forecasted values**
Return forecasted values of a BusinessMetric
#### Path Parameters
* **business\_metric\_token** (path) (string) - **Required**
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 5000.
* **start\_date** (string (date)) - Optional: Query BusinessMetrics by the first date you would like to filter from. ISO 8601 Formatted - 2021-07-15
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/businessmetrics/get-business-metric-forecasted-values](https://docs.vantage.sh/api/businessmetrics/get-business-metric-forecasted-values)
***
### GET /business\_metrics/{business_metric_token}/labels
**Get business metric labels**
Return labels of a BusinessMetric.
#### Path Parameters
* **business\_metric\_token** (path) (string) - **Required**
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* Default: `1`
* **limit** (integer (int32)) - Optional: The number of results to return per page. Defaults to 1000. The maximum is 5000.
* Default: `1000`
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/businessmetrics/get-business-metric-labels](https://docs.vantage.sh/api/businessmetrics/get-business-metric-labels)
***
### DELETE /business\_metrics/{business_metric_token}/values
**Delete business metric values**
Deletes Business Metric values (historical or forecasted unit metrics). BusinessMetrics whose values are stored in ClickHouse only support deleting every historical value or every forecasted value, so supplying start\_date, end\_date, or label returns 422.
#### Path Parameters
* **business\_metric\_token** (path) (string) - **Required**
#### Query Parameters
* **start\_date** (string) - Optional: Inclusive lower bound (ISO 8601 date or datetime, UTC). Date-only values start at 00:00:00 UTC that day.
* **end\_date** (string) - Optional: Inclusive upper bound (ISO 8601 date or datetime, UTC). Date-only values include the full calendar day through 23:59:59.999999999 UTC.
* **label** (string) - Optional: When present in the query string (including as an empty value), only unit metrics with this exact label are deleted. Omit the parameter to delete all labels in range.
* **forecasted** (boolean) - Optional: When true, deletes forecasted unit metrics instead of historical ones.
* Default: `False`
#### Responses
**200**: OK
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/businessmetrics/delete-business-metric-values](https://docs.vantage.sh/api/businessmetrics/delete-business-metric-values)
***
### GET /business\_metrics/{business_metric_token}/values
**Get business metric values**
Return values of a BusinessMetric
#### Path Parameters
* **business\_metric\_token** (path) (string) - **Required**
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 5000.
* **start\_date** (string (date)) - Optional: Query BusinessMetrics by the first date you would like to filter from. ISO 8601 Formatted - 2021-07-15
* **label\_values** (array) - Optional: Return values matching any exact label value. For multi-label metrics, matches values under any label key.
* **date\_bin** (string) - Optional: Sum values by UTC day or month while preserving labels. When omitted, values are returned without aggregation.
* Allowed values: `day`, `month`
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/businessmetrics/get-business-metric-values](https://docs.vantage.sh/api/businessmetrics/get-business-metric-values)
***
### PUT /business\_metrics/{business_metric_token}/values.csv
**Update business metric values from CSV**
Updates the values for an existing BusinessMetric from a CSV file.
#### Path Parameters
* **business\_metric\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/businessmetrics/update-business-metric-values-from-csv](https://docs.vantage.sh/api/businessmetrics/update-business-metric-values-from-csv)
***
## Canvases
### GET /canvases
**Get all canvases**
Return all Canvases.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **workspace\_token** (string) - Optional: Filter by workspace token.
* **q** (string) - Optional: Search canvases by title.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/canvases/get-all-canvases](https://docs.vantage.sh/api/canvases/get-all-canvases)
***
### POST /canvases
**Create canvas**
Create a Canvas.
#### Request Body
```json theme={null}
{
"title": string // required // The title of the Canvas,
"prompt": string // required // The prompt used to generate the Canvas,
"workspace_token": string // The token of the Workspace to add the Canvas to. Required if the API token is associated with multiple Workspaces
}
```
#### Responses
**201**: Created
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/canvases/create-canvas](https://docs.vantage.sh/api/canvases/create-canvas)
***
### DELETE /canvases/{canvas_token}
**Delete canvas**
Delete a Canvas.
#### Path Parameters
* **canvas\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/canvases/delete-canvas](https://docs.vantage.sh/api/canvases/delete-canvas)
***
### GET /canvases/{canvas_token}
**Get canvas by token**
Return a specific Canvas.
#### Path Parameters
* **canvas\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/canvases/get-canvas-by-token](https://docs.vantage.sh/api/canvases/get-canvas-by-token)
***
### PUT /canvases/{canvas_token}
**Update canvas**
Update a Canvas.
#### Path Parameters
* **canvas\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the Canvas,
"prompt": string // The prompt used to generate the Canvas
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/canvases/update-canvas](https://docs.vantage.sh/api/canvases/update-canvas)
***
## CostAlertEvents
### GET /cost\_alerts/{cost_alert_token}/events
**Get all cost alert events**
Get all CostAlertEvents
#### Path Parameters
* **cost\_alert\_token** (path) (string) - **Required**: The token of the CostAlertEvent.
#### Query Parameters
* **report\_token** (string) - Optional: The token of the report associated with the CostAlertEvent.
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The number of results to return. The maximum is 1000.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costalertevents/get-all-cost-alert-events](https://docs.vantage.sh/api/costalertevents/get-all-cost-alert-events)
***
### GET /cost\_alerts/{cost_alert_token}/events/{event_token}
**Get cost alert event by token**
Get a CostAlertEvent
#### Path Parameters
* **cost\_alert\_token** (path) (string) - **Required**
* **event\_token** (path) (string) - **Required**
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costalertevents/get-cost-alert-event-by-token](https://docs.vantage.sh/api/costalertevents/get-cost-alert-event-by-token)
***
## CostAlerts
### GET /cost\_alerts
**Get all cost alerts**
List all Cost Alerts
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 5000.
* **q** (string) - Optional: Search cost alerts by title.
* **workspace\_token** (string) - Optional: The workspace token of the cost alerts to return.
#### Responses
**200**: List all Cost Alerts
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costalerts/get-all-cost-alerts](https://docs.vantage.sh/api/costalerts/get-all-cost-alerts)
***
### POST /cost\_alerts
**Create cost alert**
Create a new Cost Alert
#### Request Body
```json theme={null}
{
"title": string // required // The title of the Cost Alert,
"interval": string // required // The period of time used to compare costs. Options are 'day', 'week', 'month', 'quarter',
"threshold": number // required // The threshold value for the Cost Alert,
"unit_type": string // required // The unit type used to compare costs. Options are 'currency' or 'percentage',
"workspace_token": string // required // The token of the Workspace to add the Cost Alert to,
"report_tokens": [string] // required // The tokens of the reports to alert on,
"email_recipients": [string] // The email recipients for the Cost Alert. Accepts organization users, SSO-domain emails, and approved third-party service emails,
"slack_channels": [string] // The Slack channels that will receive the alert,
"teams_channels": [string] // The Microsoft Teams channels that will receive the alert,
"minimum_threshold": number // The minimum monetary amount threshold for percentage-based alerts. Only applicable when unit_type is 'percentage'
}
```
#### Responses
**201**: Cost Alert created successfully.
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costalerts/create-cost-alert](https://docs.vantage.sh/api/costalerts/create-cost-alert)
***
### DELETE /cost\_alerts/{cost_alert_token}
**Delete cost alert**
Delete a Cost Alert
#### Path Parameters
* **cost\_alert\_token** (path) (string) - **Required**: The token of the Cost Alert.
#### Responses
**204**: Cost Alert deleted successfully.
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costalerts/delete-cost-alert](https://docs.vantage.sh/api/costalerts/delete-cost-alert)
***
### GET /cost\_alerts/{cost_alert_token}
**Get cost alert by token**
Get a Cost Alert
#### Path Parameters
* **cost\_alert\_token** (path) (string) - **Required**: The token of the Cost Alert.
#### Responses
**200**: Get a Cost Alert
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costalerts/get-cost-alert-by-token](https://docs.vantage.sh/api/costalerts/get-cost-alert-by-token)
***
### PUT /cost\_alerts/{cost_alert_token}
**Update cost alert**
Update a Cost Alert
#### Path Parameters
* **cost\_alert\_token** (path) (string) - **Required**: The token of the Cost Alert.
#### Request Body
```json theme={null}
{
"title": string // The title of the Cost Alert,
"email_recipients": [string] // The email recipients for the Cost Alert. Accepts organization users, SSO-domain emails, and approved third-party service emails,
"interval": string // The period of time used to compare costs. Options are 'day', 'week', 'month', 'quarter',
"threshold": number // The threshold value for the Cost Alert,
"slack_channels": [string] // The Slack channels that will receive the alert. Make sure your slack integration is connected at https://console.vantage.sh/settings/slack,
"teams_channels": [string] // The Microsoft Teams channels that will receive the alert. Make sure your teams integration is connected at https://console.vantage.sh/settings/microsoft_teams,
"unit_type": string // The unit type used to compare costs. Options are 'currency' or 'percentage',
"report_tokens": [string] // The tokens of the reports to alert on,
"minimum_threshold": number // The minimum monetary amount threshold for percentage-based alerts. Only applicable when unit_type is 'percentage'
}
```
#### Responses
**200**: Cost Alert updated successfully.
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costalerts/update-cost-alert](https://docs.vantage.sh/api/costalerts/update-cost-alert)
***
## CostProvider
### GET /cost\_providers
**Get cost providers**
List CostProviders available to query in a given Workspace.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The number of results to return. The maximum is 1000.
* **workspace\_token** (string) - Optional: The token of the Workspace to list CostProviders for. Required if the API token is associated with multiple Workspaces.
* **q** (string) - Optional: Search CostProviders by name or key.
#### Responses
**200**: List of connected CostProviders.
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costprovider/get-cost-providers](https://docs.vantage.sh/api/costprovider/get-cost-providers)
***
## CostProviderAccounts
### GET /cost\_provider\_accounts
**Get all cost provider accounts**
List CostProviderAccounts available in a given Workspace.
#### Query Parameters
* **workspace\_token** (string) - Optional: The token of the Workspace to list CostProviderAccounts for. Required if the API token is associated with multiple Workspaces.
* **provider** (string) - Optional: Filter by provider type.
* Allowed values: `aws`, `azure`, `gcp`, `snowflake`, `databricks`, `mongo`, `datadog`, `fastly`, `new_relic`, `opencost`, `open_ai`, `oracle`, `confluent`, `planetscale`, `coralogix`, `kubernetes`, `custom_provider`, `github`, `linode`, `grafana`, `clickhouse`, `temporal`, `twilio`, `azure_csp`, `kubernetes_agent`, `anthropic`, `anyscale`, `cursor`, `elastic`, `vercel`, `redis_cloud`, `circle_ci`, `modal`, `eleven_labs`, `baseten`, `cloudflare`, `fireworks_ai`, `cartesia`, `depot`, `xai`, `digital_ocean`, `together_ai`, `coreweave`, `devin`, `openrouter`, `deepgram`, `crusoe`, `sentry_billing`, `ramp`
* **account\_id** (string) - Optional: Filter by provider account identifier.
* **account\_name** (string) - Optional: Filter by account name (exact match).
* **q** (string) - Optional: Search CostProviderAccounts by title.
#### Responses
**200**: List of provider accounts.
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costprovideraccounts/get-all-cost-provider-accounts](https://docs.vantage.sh/api/costprovideraccounts/get-all-cost-provider-accounts)
***
## CostService
### GET /cost\_services
**Get cost services**
List CostServices available to query in a given Workspace.
#### Query Parameters
* **workspace\_token** (string) - Optional: The token of the Workspace to list CostServices for. Required if the API token is associated with multiple Workspaces.
#### Responses
**200**: List of CostServices, used to query costs using VQL.
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costservice/get-cost-services](https://docs.vantage.sh/api/costservice/get-cost-services)
***
## Costs
### GET /cost\_reports
**Get all cost reports**
Return all CostReports.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **folder\_token** (string) - Optional: The token for the Folder you would like to fetch Reports from.
* **q** (string) - Optional: Search cost reports by title.
* **workspace\_token** (string) - Optional: The workspace token of the cost reports to return.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costs/get-all-cost-reports](https://docs.vantage.sh/api/costs/get-all-cost-reports)
***
### POST /cost\_reports
**Create cost report**
Create a CostReport.
#### Request Body
```json theme={null}
{
"title": string // required // The title of the CostReport,
"workspace_token": string // The token of the Workspace to add the Cost Report to. Ignored if 'folder_token' is set. Required if the API token is associated with multiple Workspaces,
"groupings": string // Grouping values for aggregating costs on the report. Valid groupings: account_id, billing_account_id, charge_type, cost_category, cost_subcategory, provider, region, resource_id, service, tagged, usage_unit, tag:tag_value. If providing multiple groupings, join as comma separated values: groupings=provider,service,region,
"filter": string // The filter query language to apply to the CostReport. Additional documentation available at https://docs.vantage.sh/vql,
"saved_filter_tokens": [string] // The tokens of the SavedFilters to apply to the CostReport,
"business_metric_tokens_with_metadata": [ // The tokens for any BusinessMetrics to attach to the CostReport, and the unit scale
{
"business_metric_token": string // required // The token of the BusinessMetric to attach to the CostReport,
"unit_scale": string // Determines the scale of the BusinessMetric's values within the CostReport. Allowed values: `per_unit`, `per_hundred`, `per_thousand`, `per_million`, `per_billion`,
"calculation_type": string // The calculation type applied when this BusinessMetric is used in the CostReport. Allowed values: `unit_cost`, `gross_margin`, `usage_unit_cost`, `raw_business_metric`,
"label": string // Optional custom display name for this BusinessMetric on the CostReport. When omitted, a default is derived from the calculation type,
"label_filter": [string] // Include only values with these labels in the CostReport,
"label_filters": object // Include only ClickHouse BusinessMetric values matching every label key and one of its values
}
],
"folder_token": string // The token of the Folder to add the CostReport to. Determines the Workspace the report is assigned to,
"settings": { // Report settings
"include_credits": boolean // Report will include credits,
"include_refunds": boolean // Report will include refunds,
"include_discounts": boolean // Report will include discounts,
"include_tax": boolean // Report will include tax,
"amortize": boolean // Report will amortize,
"unallocated": boolean // Report will show unallocated costs,
"aggregate_by": string // Report will aggregate by cost, usage, or count. Allowed values: `cost`, `usage`, `count`,
"show_previous_period": boolean // Report will show previous period cost, usage, or count comparison,
"complete_period": boolean // Report will restrict date ranges to completed periods only
},
"previous_period_start_date": string // The previous period start date of the CostReport. ISO 8601 Formatted,
"previous_period_end_date": string // required // The previous period end date of the CostReport. ISO 8601 Formatted. Required when previous_period_start_date is provided,
"start_date": string // The start date of the CostReport. ISO 8601 Formatted. Incompatible with 'date_interval' parameter,
"end_date": string // required // The end date of the CostReport. ISO 8601 Formatted. Required when start_date is provided. Incompatible with 'date_interval' parameter,
"date_interval": string // The date interval of the CostReport. Incompatible with 'start_date' and 'end_date' parameters. Defaults to 'this_month' if start_date and end_date are not provided. Allowed values: `this_month`, `last_7_days`, `last_30_days`, `last_month`, `last_3_months`, `last_6_months`, `custom`, `last_12_months`, `last_24_months`, `last_36_months`, `next_month`, `next_3_months`, `next_6_months`, `next_12_months`, `year_to_date`, `last_3_days`, `last_14_days`,
"chart_type": string // The chart type of the CostReport. Allowed values: `area`, `line`, `pie`, `bar`, `multi_bar`,
"date_bin": string // The date bin of the CostReport. Allowed values: `cumulative`, `day`, `week`, `month`, `quarter`, `hour`,
"chart_settings": { // Report chart settings
"x_axis_dimension": [string] // The dimension used to group or label data along the x-axis (e.g., by date, region, or service). NOTE: Only one value is allowed at this time. Defaults to ['date'],
"y_axis_dimension": string // The metric or measure displayed on the chart’s y-axis. Possible values: 'cost', 'usage', 'count'. Defaults to 'cost'. Allowed values: `cost`, `usage`, `count`
}
}
```
#### Responses
**201**: Created
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costs/create-cost-report](https://docs.vantage.sh/api/costs/create-cost-report)
***
### DELETE /cost\_reports/{cost_report_token}
**Delete cost report**
Delete a CostReport.
#### Path Parameters
* **cost\_report\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costs/delete-cost-report](https://docs.vantage.sh/api/costs/delete-cost-report)
***
### GET /cost\_reports/{cost_report_token}
**Get cost report by token**
Return a CostReport.
#### Path Parameters
* **cost\_report\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costs/get-cost-report-by-token](https://docs.vantage.sh/api/costs/get-cost-report-by-token)
***
### PUT /cost\_reports/{cost_report_token}
**Update cost report**
Update a CostReport.
#### Path Parameters
* **cost\_report\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the CostReport,
"groupings": string // Grouping values for aggregating costs on the report. Valid groupings: account_id, billing_account_id, charge_type, cost_category, cost_subcategory, provider, region, resource_id, service, tagged, usage_unit, tag:tag_value. If providing multiple groupings, join as comma separated values: groupings=provider,service,region,
"filter": string // The filter query language to apply to the CostReport. Additional documentation available at https://docs.vantage.sh/vql,
"saved_filter_tokens": [string] // The tokens of the SavedFilters to apply to the CostReport,
"business_metric_tokens_with_metadata": [ // The tokens for any BusinessMetrics to attach to the CostReport, and the unit scale
{
"business_metric_token": string // required // The token of the BusinessMetric to attach to the CostReport,
"unit_scale": string // Determines the scale of the BusinessMetric's values within the CostReport. Allowed values: `per_unit`, `per_hundred`, `per_thousand`, `per_million`, `per_billion`,
"calculation_type": string // The calculation type applied when this BusinessMetric is used in the CostReport. Allowed values: `unit_cost`, `gross_margin`, `usage_unit_cost`, `raw_business_metric`,
"label": string // Optional custom display name for this BusinessMetric on the CostReport. When omitted, a default is derived from the calculation type,
"label_filter": [string] // Include only values with these labels in the CostReport,
"label_filters": object // Include only ClickHouse BusinessMetric values matching every label key and one of its values
}
],
"folder_token": string // The token of the Folder to add the CostReport to. Determines the Workspace the report is assigned to,
"default_forecast": { // The default forecast selection for the CostReport
"kind": string // required // The default forecast selection kind. Allowed values: `baseline`, `report_forecast`,
"report_forecast_token": string // The token for the report forecast to set as default when kind is report_forecast
},
"settings": { // Report settings
"include_credits": boolean // Report will include credits,
"include_refunds": boolean // Report will include refunds,
"include_discounts": boolean // Report will include discounts,
"include_tax": boolean // Report will include tax,
"amortize": boolean // Report will amortize,
"unallocated": boolean // Report will show unallocated costs,
"aggregate_by": string // Report will aggregate by cost, usage, or count. Allowed values: `cost`, `usage`, `count`,
"show_previous_period": boolean // Report will show previous period cost, usage, or count comparison,
"complete_period": boolean // Report will restrict date ranges to completed periods only
},
"chart_settings": { // Report chart settings
"x_axis_dimension": [string] // The dimension used to group or label data along the x-axis (e.g., by date, region, or service). NOTE: Only one value is allowed at this time. Defaults to ['date'],
"y_axis_dimension": string // The metric or measure displayed on the chart’s y-axis. Possible values: 'cost', 'usage', 'count'. Defaults to 'cost'. Allowed values: `cost`, `usage`, `count`
},
"previous_period_start_date": string // The previous period start date of the CostReport. ISO 8601 Formatted,
"previous_period_end_date": string // The previous period end date of the CostReport. ISO 8601 Formatted. Required when previous_period_start_date is provided,
"start_date": string // The start date of the CostReport. ISO 8601 Formatted. Incompatible with 'date_interval' parameter,
"end_date": string // The end date of the CostReport. ISO 8601 Formatted. Required when start_date is provided. Incompatible with 'date_interval' parameter,
"date_interval": string // The date interval of the CostReport. Incompatible with 'start_date' and 'end_date' parameters. Defaults to 'this_month' if start_date and end_date are not provided. Allowed values: `this_month`, `last_7_days`, `last_30_days`, `last_month`, `last_3_months`, `last_6_months`, `custom`, `last_12_months`, `last_24_months`, `last_36_months`, `next_month`, `next_3_months`, `next_6_months`, `next_12_months`, `year_to_date`, `last_3_days`, `last_14_days`,
"chart_type": string // The chart type of the CostReport. Allowed values: `area`, `line`, `pie`, `bar`, `multi_bar`,
"date_bin": string // The date bin of the CostReport. Allowed values: `cumulative`, `day`, `week`, `month`, `quarter`, `hour`
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costs/update-cost-report](https://docs.vantage.sh/api/costs/update-cost-report)
***
### GET /cost\_reports/{cost_report_token}/forecasted\_costs
**Get forecasted costs for a cost report**
Return all ForecastedCosts.
#### Path Parameters
* **cost\_report\_token** (path) (string) - **Required**
#### Query Parameters
* **start\_date** (string (date)) - Optional: First date you would like to filter forecasted costs from. ISO 8601 formatted.
* **end\_date** (string (date)) - Optional: Last date you would like to filter forecasted costs from. ISO 8601 formatted.
* **provider** (string) - Optional: Limit the forecasted costs to a specific provider. 'all' is accepted to filter to overall forecast.
* Allowed values: `aws`, `azure`, `gcp`, `snowflake`, `databricks`, `mongo`, `datadog`, `fastly`, `new_relic`, `opencost`, `open_ai`, `oracle`, `confluent`, `planetscale`, `coralogix`, `kubernetes`, `custom_provider`, `github`, `linode`, `grafana`, `clickhouse`, `temporal`, `twilio`, `azure_csp`, `kubernetes_agent`, `anthropic`, `anyscale`, `cursor`, `elastic`, `vercel`, `redis_cloud`, `circle_ci`, `modal`, `eleven_labs`, `baseten`, `cloudflare`, `fireworks_ai`, `cartesia`, `depot`, `xai`, `digital_ocean`, `together_ai`, `coreweave`, `devin`, `openrouter`, `deepgram`, `crusoe`, `sentry_billing`, `ramp`, `all`
* **service** (string) - Optional: Limit the forecasted costs to a specific service. 'all' is accepted to filter to overall forecast. e.g. 'Amazon ElastiCache'.
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costs/get-forecasted-costs-for-a-cost-report](https://docs.vantage.sh/api/costs/get-forecasted-costs-for-a-cost-report)
***
### GET /costs
**Get costs for cost report or VQL filter**
Return all Costs for a CostReport or VQL filter.
#### Query Parameters
* **cost\_report\_token** (string) - Optional: The CostReport token.
* **filter** (string) - Optional: The VQL filter to apply to the costs. If this is supplied you do not need cost\_report\_token.
* **workspace\_token** (string) - Optional: The token of the Workspace to query costs from. Ignored if 'cost\_report\_token' is set. Required if the API token is associated with multiple Workspaces.
* **start\_date** (string) - Optional: First date you would like to filter costs from. ISO 8601 formatted. When omitted with cost\_report\_token, the report's saved start date is used.
* **end\_date** (string) - Optional: Last date you would like to filter costs to. ISO 8601 formatted. When omitted with cost\_report\_token, the report's saved end date is used.
* **groupings** (array) - Optional: Group the results by specific field(s). When omitted with cost\_report\_token, the report's saved groupings are used; otherwise defaults to provider, service, account\_id. Valid groupings: account\_id, billing\_account\_id, charge\_type, cost\_category, cost\_subcategory, provider, region, resource\_id, service, tagged, usage\_unit, tag:tag\_value. If providing multiple groupings, join as comma separated values: groupings=provider,service,region
* **order** (string) - Optional: Whether to order costs by date in ascending or descending order. Defaults to desc.
* Allowed values: `asc`, `desc`
* Default: `desc`
* **sort\_column** (string) - Optional: Sort results by one of the fields in groupings. Valid groupings: account\_id, billing\_account\_id, charge\_type, cost\_category, cost\_subcategory, provider, region, resource\_id, service, tagged, usage\_unit, tag:tag\_value. Defaults to sorting by date.
* **sort\_direction** (string) - Optional: Sort direction for sort\_column. Defaults to asc. Requires sort\_column.
* Allowed values: `asc`, `desc`
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 5000.
* **page** (integer (int32)) - Optional: The page of results to return.
* **date\_bin** (string) - Optional: The date bin of the costs. Defaults to the report's default or day.
* Allowed values: `day`, `week`, `month`, `quarter`, `hour`
* **settings\[include\_credits]** (boolean) - Optional: Results will include credits.
* **settings\[include\_refunds]** (boolean) - Optional: Results will include refunds.
* **settings\[include\_discounts]** (boolean) - Optional: Results will include discounts.
* **settings\[include\_tax]** (boolean) - Optional: Results will include tax.
* **settings\[amortize]** (boolean) - Optional: Results will amortize.
* **settings\[unallocated]** (boolean) - Optional: Results will show unallocated costs.
* **settings\[aggregate\_by]** (string) - Optional: Results will aggregate by cost, usage, or count.
* Allowed values: `cost`, `usage`, `count`
* **settings\[show\_previous\_period]** (boolean) - Optional: Results will show previous period cost, usage, or count comparison.
#### Responses
**200**: OK
**400**: BadRequest
**402**: PaymentRequired
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costs/get-costs-for-cost-report-or-vql-filter](https://docs.vantage.sh/api/costs/get-costs-for-cost-report-or-vql-filter)
***
### POST /costs/data\_exports
**Generate cost data export**
Generate a DataExport of costs.
#### Request Body
```json theme={null}
{
"cost_report_token": string // The CostReport token,
"filter": string // The VQL filter to apply to the costs. If this is supplied you do not need cost_report_token,
"workspace_token": string // The token of the Workspace to query costs from. Ignored if 'cost_report_token' is set. Required if the API token is associated with multiple Workspaces,
"start_date": string // First date you would like to filter costs from. ISO 8601 formatted. When omitted with cost_report_token, the report's saved start date is used,
"end_date": string // Last date you would like to filter costs to. ISO 8601 formatted. When omitted with cost_report_token, the report's saved end date is used,
"groupings": [string] // Group the results by specific field(s). When omitted with cost_report_token, the report's saved groupings are used; otherwise defaults to provider, service, account_id. Valid groupings: account_id, billing_account_id, charge_type, cost_category, cost_subcategory, provider, region, resource_id, service, tagged, usage_unit, tag:tag_value. If providing multiple groupings, join as comma separated values: groupings=provider,service,region,
"date_bin": string // The date bin of the costs. Defaults to the report's default or day. Allowed values: `day`, `week`, `month`, `quarter`, `hour`,
"schema": string // The schema of the data export. Allowed values: `vntg`, `focus`, `comparison`,
"settings": { // Cost-related settings
"include_credits": boolean // Results will include credits,
"include_refunds": boolean // Results will include refunds,
"include_discounts": boolean // Results will include discounts,
"include_tax": boolean // Results will include tax,
"amortize": boolean // Results will amortize,
"unallocated": boolean // Results will show unallocated costs,
"aggregate_by": string // Results will aggregate by cost, usage, or count. Allowed values: `cost`, `usage`, `count`,
"show_previous_period": boolean // Results will show previous period cost, usage, or count comparison
}
}
```
#### Responses
**202**: The data export has been queued and will be available at the location specified in the Location header.
**400**: BadRequest
**402**: PaymentRequired
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/costs/generate-cost-data-export](https://docs.vantage.sh/api/costs/generate-cost-data-export)
***
## DashboardNotifications
### GET /dashboard\_notifications
**Get all dashboard notifications**
Return all DashboardNotifications.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **q** (string) - Optional: Search dashboard notifications by title.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dashboardnotifications/get-all-dashboard-notifications](https://docs.vantage.sh/api/dashboardnotifications/get-all-dashboard-notifications)
***
### POST /dashboard\_notifications
**Create dashboard notification**
Create a DashboardNotification.
#### Request Body
```json theme={null}
{
"title": string // required // The title of the DashboardNotification,
"dashboard_token": string // required // The Dashboard token,
"workspace_token": string // The token of the Workspace to add the DashboardNotification to. Required if the API token is associated with multiple Workspaces,
"user_tokens": [string] // The Users that receive the notification,
"recipient_emails": [string] // Email addresses that receive the notification. Must be organization users, on the account's SSO domain, or an approved third-party service address,
"frequency": string // required // The frequency the DashboardNotification is sent. Possible values: daily, weekly, monthly. Allowed values: `daily`, `weekly`, `monthly`
}
```
#### Responses
**201**: Created
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dashboardnotifications/create-dashboard-notification](https://docs.vantage.sh/api/dashboardnotifications/create-dashboard-notification)
***
### DELETE /dashboard\_notifications/{dashboard_notification_token}
**Delete dashboard notification**
Delete a DashboardNotification.
#### Path Parameters
* **dashboard\_notification\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dashboardnotifications/delete-dashboard-notification](https://docs.vantage.sh/api/dashboardnotifications/delete-dashboard-notification)
***
### GET /dashboard\_notifications/{dashboard_notification_token}
**Get dashboard notification by token**
Return a DashboardNotification.
#### Path Parameters
* **dashboard\_notification\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dashboardnotifications/get-dashboard-notification-by-token](https://docs.vantage.sh/api/dashboardnotifications/get-dashboard-notification-by-token)
***
### PUT /dashboard\_notifications/{dashboard_notification_token}
**Update dashboard notification**
Update a DashboardNotification.
#### Path Parameters
* **dashboard\_notification\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the DashboardNotification,
"dashboard_token": string // The Dashboard token. Retargeting requires edit access to the new Dashboard,
"user_tokens": [string] // The Users that receive the notification,
"recipient_emails": [string] // Email addresses that receive the notification. Must be organization users, on the account's SSO domain, or an approved third-party service address,
"frequency": string // The frequency the DashboardNotification is sent. Possible values: daily, weekly, monthly. Allowed values: `daily`, `weekly`, `monthly`
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dashboardnotifications/update-dashboard-notification](https://docs.vantage.sh/api/dashboardnotifications/update-dashboard-notification)
***
## Dashboards
### GET /dashboards
**Get all dashboards**
Return all Dashboards.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **q** (string) - Optional: Search dashboards by title.
* **workspace\_token** (string) - Optional: The workspace token of the dashboards to return.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dashboards/get-all-dashboards](https://docs.vantage.sh/api/dashboards/get-all-dashboards)
***
### POST /dashboards
**Create dashboard**
Create a Dashboard.
#### Request Body
```json theme={null}
{
"title": string // required // The title of the Dashboard,
"widgets": [ // The widgets to add to the Dashboard. Report-backed widgets use widgetable_token. Free text widgets use widgetable_type set to free_text and require content
{
"widgetable_token": string // The token of the represented Resource,
"widgetable_type": string // The widget type. Use free_text for a free text widget. Allowed values: `free_text`,
"title": string // The title of the Widget (defaults to the Resource title, or Free Text for a free text widget),
"content": { // Rich-text document for a free text widget, for example {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Note"}]}]}
"type": string // required // Document root. Must be doc. Allowed values: `doc`,
"content": [object]
},
"settings": { // The display and grid layout settings for the DashboardWidget
"display_type": string // required // Allowed values: `table`, `chart`, `kpi`,
"kpi_calculation": string // The aggregation used when display_type is kpi. Allowed values: `sum`, `average`,
"kpi_type": string // The metric represented when display_type is kpi. Allowed values: `cost`, `usage`, `count`, `business_metric`,
"kpi_usage_unit": string // The usage unit represented when kpi_type is usage,
"grid": { // The widget's size and position in the dashboard's 12-column grid
"x": integer // required // The zero-based horizontal position,
"y": integer // required // The zero-based vertical position,
"w": integer // required // The widget width in grid columns,
"h": integer // required // The widget height in grid rows
}
}
}
],
"saved_filter_tokens": [string] // The tokens of the Saved Filters used in the Dashboard,
"date_bin": string // Determines how to group costs in the Dashboard. Allowed values: `cumulative`, `day`, `week`, `month`,
"date_interval": string // Determines the date range in the Dashboard. Incompatible with 'start_date' and 'end_date' parameters. Allowed values: `this_month`, `last_7_days`, `last_30_days`, `last_month`, `last_3_months`, `last_6_months`, `custom`, `last_12_months`, `last_24_months`, `last_36_months`, `next_month`, `next_3_months`, `next_6_months`, `next_12_months`, `year_to_date`, `last_3_days`, `last_14_days`,
"start_date": string // The start date for the date range for costs in the Dashboard. ISO 8601 Formatted. Incompatible with 'date_interval' parameter,
"end_date": string // The end date for the date range for costs in the Dashboard. ISO 8601 Formatted. Incompatible with 'date_interval' parameter,
"workspace_token": string // The token of the Workspace to add the Dashboard to. Required if the API token is associated with multiple Workspaces
}
```
#### Responses
**201**: Created
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dashboards/create-dashboard](https://docs.vantage.sh/api/dashboards/create-dashboard)
***
### DELETE /dashboards/{dashboard_token}
**Delete dashboard**
Delete a Dashboard.
#### Path Parameters
* **dashboard\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dashboards/delete-dashboard](https://docs.vantage.sh/api/dashboards/delete-dashboard)
***
### GET /dashboards/{dashboard_token}
**Get dashboard by token**
Return a specific Dashboard.
#### Path Parameters
* **dashboard\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dashboards/get-dashboard-by-token](https://docs.vantage.sh/api/dashboards/get-dashboard-by-token)
***
### PUT /dashboards/{dashboard_token}
**Update dashboard**
Update a Dashboard.
#### Path Parameters
* **dashboard\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the Dashboard,
"widgets": [ // The complete replacement list of widgets for the Dashboard. Omit widgets or send null to preserve every existing widget. When provided, include every report-backed and free text widget to keep; an empty array removes all widgets. Report-backed widgets use widgetable_token. Free text widgets use widgetable_type set to free_text and require content
{
"widgetable_token": string // The token of the represented Resource,
"widgetable_type": string // The widget type. Use free_text for a free text widget. Allowed values: `free_text`,
"title": string // The title of the Widget (defaults to the Resource title, or Free Text for a free text widget),
"content": { // Rich-text document for a free text widget, for example {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Note"}]}]}
"type": string // required // Document root. Must be doc. Allowed values: `doc`,
"content": [object]
},
"settings": { // The display and grid layout settings for the DashboardWidget
"display_type": string // required // Allowed values: `table`, `chart`, `kpi`,
"kpi_calculation": string // The aggregation used when display_type is kpi. Allowed values: `sum`, `average`,
"kpi_type": string // The metric represented when display_type is kpi. Allowed values: `cost`, `usage`, `count`, `business_metric`,
"kpi_usage_unit": string // The usage unit represented when kpi_type is usage,
"grid": { // The widget's size and position in the dashboard's 12-column grid
"x": integer // required // The zero-based horizontal position,
"y": integer // required // The zero-based vertical position,
"w": integer // required // The widget width in grid columns,
"h": integer // required // The widget height in grid rows
}
}
}
],
"saved_filter_tokens": [string] // The tokens of the Saved Filters used in the Dashboard,
"date_bin": string // Determines how to group costs in the Dashboard. Allowed values: `cumulative`, `day`, `week`, `month`,
"date_interval": string // Determines the date range in the Dashboard. Incompatible with 'start_date' and 'end_date' parameters. Allowed values: `this_month`, `last_7_days`, `last_30_days`, `last_month`, `last_3_months`, `last_6_months`, `custom`, `last_12_months`, `last_24_months`, `last_36_months`, `next_month`, `next_3_months`, `next_6_months`, `next_12_months`, `year_to_date`, `last_3_days`, `last_14_days`, ``,
"start_date": string // The start date for the date range for costs in the Dashboard. ISO 8601 Formatted. Incompatible with 'date_interval' parameter,
"end_date": string // The end date for the date range for costs in the Dashboard. ISO 8601 Formatted. Incompatible with 'date_interval' parameter,
"workspace_token": string // The token of the Workspace the Dashboard belongs to. Required when updating widgets if the API token is associated with multiple Workspaces
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dashboards/update-dashboard](https://docs.vantage.sh/api/dashboards/update-dashboard)
***
### DELETE /widgets/{widget_token}
**Delete dashboard widget**
Delete a Dashboard Widget.
#### Path Parameters
* **widget\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**403**: Forbidden
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dashboards/delete-dashboard-widget](https://docs.vantage.sh/api/dashboards/delete-dashboard-widget)
***
### GET /widgets/{widget_token}
**Get dashboard widget**
Return a Dashboard Widget.
#### Path Parameters
* **widget\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dashboards/get-dashboard-widget](https://docs.vantage.sh/api/dashboards/get-dashboard-widget)
***
### PATCH /widgets/{widget_token}
**Update dashboard widget**
Update a single Dashboard Widget.
#### Path Parameters
* **widget\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"widgetable_token": string // The token of the Resource represented by the Widget,
"title": string // The title of the Widget,
"settings": { // The settings for the DashboardWidget
"display_type": string // Allowed values: `table`, `chart`, `kpi`,
"kpi_calculation": string // Allowed values: `sum`, `average`,
"kpi_type": string // Allowed values: `cost`, `usage`, `count`, `business_metric`,
"kpi_usage_unit": string
}
}
```
#### Responses
**200**: OK
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dashboards/update-dashboard-widget](https://docs.vantage.sh/api/dashboards/update-dashboard-widget)
***
## DataExports
### GET /data\_exports/{data_export_token}
**Get status of data export**
Get the status of a data export.
#### Path Parameters
* **data\_export\_token** (path) (string) - **Required**
#### Responses
**200**: Returns the completed data export and its manifest. If it is still pending, the response will be a 202 and the caller should check the Location and Retry-After headers to determine where and how long to wait before polling again.
**400**: BadRequest
**402**: PaymentRequired
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/dataexports/get-status-of-data-export](https://docs.vantage.sh/api/dataexports/get-status-of-data-export)
***
## EnrichmentSources
### GET /enrichment\_sources
**Get all enrichment sources**
Return all EnrichmentSources.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The number of results to return. The maximum is 1000.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/enrichmentsources/get-all-enrichment-sources](https://docs.vantage.sh/api/enrichmentsources/get-all-enrichment-sources)
***
### GET /enrichment\_sources/{enrichment_source_token}
**Get enrichment source by token**
Return an EnrichmentSource.
#### Path Parameters
* **enrichment\_source\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/enrichmentsources/get-enrichment-source-by-token](https://docs.vantage.sh/api/enrichmentsources/get-enrichment-source-by-token)
***
## EnrichmentStatistics
### GET /enrichment\_sources/{enrichment_source_token}/statistics
**Get enrichment statistics**
Return enrichment statistics.
#### Path Parameters
* **enrichment\_source\_token** (path) (string) - **Required**
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* Default: `1`
* **limit** (integer (int32)) - Optional: The number of results to return. The maximum is 1000.
* Default: `50`
* **provider** (string) - Optional: Filter statistics to costs for a specific provider key.
* Allowed values: `aws`, `azure`, `gcp`, `snowflake`, `databricks`, `mongo`, `datadog`, `fastly`, `new_relic`, `opencost`, `open_ai`, `oracle`, `confluent`, `planetscale`, `coralogix`, `kubernetes`, `custom_provider`, `github`, `linode`, `grafana`, `clickhouse`, `temporal`, `twilio`, `azure_csp`, `kubernetes_agent`, `anthropic`, `anyscale`, `cursor`, `elastic`, `vercel`, `redis_cloud`, `circle_ci`, `modal`, `eleven_labs`, `baseten`, `cloudflare`, `fireworks_ai`, `cartesia`, `depot`, `xai`, `digital_ocean`, `together_ai`, `coreweave`, `devin`, `openrouter`, `deepgram`, `crusoe`, `sentry_billing`, `ramp`
* Example: `aws`
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/enrichmentstatistics/get-enrichment-statistics](https://docs.vantage.sh/api/enrichmentstatistics/get-enrichment-statistics)
***
## ExchangeRates
### GET /exchange\_rates
**Get all exchange rates**
Return all Exchange Rates.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The number of results to return. The maximum is 1000.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/exchangerates/get-all-exchange-rates](https://docs.vantage.sh/api/exchangerates/get-all-exchange-rates)
***
### POST /exchange\_rates/csv
**Upload exchange rates via CSV**
Upload Exchange Rates via CSV.
#### Responses
**201**: CSV uploaded successfully
**400**: BadRequest
**403**: Forbidden
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/exchangerates/upload-exchange-rates-via-csv](https://docs.vantage.sh/api/exchangerates/upload-exchange-rates-via-csv)
***
## FinancialCommitmentReports
### GET /financial\_commitment\_reports
**Get all financial commitment reports**
Return all FinancialCommitmentReports.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **q** (string) - Optional: Search financial commitment reports by title.
* **workspace\_token** (string) - Optional: The workspace token of the financial commitment reports to return.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/financialcommitmentreports/get-all-financial-commitment-reports](https://docs.vantage.sh/api/financialcommitmentreports/get-all-financial-commitment-reports)
***
### POST /financial\_commitment\_reports
**Create financial commitment report**
Create a FinancialCommitmentReport.
#### Request Body
```json theme={null}
{
"workspace_token": string // required // The Workspace in which the FinancialCommitmentReport will be created,
"title": string // required // The title of the FinancialCommitmentReport,
"filter": string // The filter query language to apply to the FinancialCommitmentReport. Additional documentation available at https://docs.vantage.sh/vql,
"start_date": string // The start date of the FinancialCommitmentReport. YYYY-MM-DD formatted. Incompatible with 'date_interval' parameter,
"end_date": string // The end date of the FinancialCommitmentReport. YYYY-MM-DD formatted. Incompatible with 'date_interval' parameter,
"date_interval": string // The date interval of the FinancialCommitmentReport. Unless 'custom' is used, this is incompatible with 'start_date' and 'end_date' parameters. Defaults to 'last_3_months'. Allowed values: `this_month`, `last_7_days`, `last_30_days`, `last_month`, `last_3_months`, `last_6_months`, `custom`, `last_12_months`, `last_24_months`, `last_36_months`, `year_to_date`, `last_3_days`, `last_14_days`,
"date_bucket": string // The date bucket of the FinancialCommitmentReport. Allowed values: `hour`, `day`, `week`, `month`, `quarter`,
"on_demand_costs_scope": string // The scope for the costs. Possible values: discountable, all. Allowed values: `discountable`, `all`,
"groupings": [string] // Grouping values for aggregating costs on the FinancialCommitmentReport. Group by up to 100 fields. Valid groupings: cost_type, provider, commitment_type, commitment_id, service, resource_account_id, provider_account_id, region, cost_category, cost_sub_category, instance_type, tag:label_name
}
```
#### Responses
**201**: Created
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/financialcommitmentreports/create-financial-commitment-report](https://docs.vantage.sh/api/financialcommitmentreports/create-financial-commitment-report)
***
### DELETE /financial\_commitment\_reports/{financial_commitment_report_token}
**Delete financial commitment report**
Delete a FinancialCommitmentReport.
#### Path Parameters
* **financial\_commitment\_report\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/financialcommitmentreports/delete-financial-commitment-report](https://docs.vantage.sh/api/financialcommitmentreports/delete-financial-commitment-report)
***
### GET /financial\_commitment\_reports/{financial_commitment_report_token}
**Get financial commitment report by token**
Return a FinancialCommitmentReport.
#### Path Parameters
* **financial\_commitment\_report\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/financialcommitmentreports/get-financial-commitment-report-by-token](https://docs.vantage.sh/api/financialcommitmentreports/get-financial-commitment-report-by-token)
***
### PUT /financial\_commitment\_reports/{financial_commitment_report_token}
**Update financial commitment report**
Update a FinancialCommitmentReport.
#### Path Parameters
* **financial\_commitment\_report\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the FinancialCommitmentReport,
"filter": string // The filter query language to apply to the FinancialCommitmentReport. Additional documentation available at https://docs.vantage.sh/vql,
"start_date": string // The start date of the FinancialCommitmentReport. YYYY-MM-DD formatted. Incompatible with 'date_interval' parameter,
"end_date": string // The end date of the FinancialCommitmentReport. YYYY-MM-DD formatted. Incompatible with 'date_interval' parameter,
"date_interval": string // The date interval of the FinancialCommitmentReport. Unless 'custom' is used, this is incompatible with 'start_date' and 'end_date' parameters. Defaults to 'last_3_months'. Allowed values: `this_month`, `last_7_days`, `last_30_days`, `last_month`, `last_3_months`, `last_6_months`, `custom`, `last_12_months`, `last_24_months`, `last_36_months`, `year_to_date`, `last_3_days`, `last_14_days`,
"date_bucket": string // The date bucket of the FinancialCommitmentReport. Allowed values: `hour`, `day`, `week`, `month`, `quarter`,
"on_demand_costs_scope": string // The scope for the costs. Possible values: discountable, all. Allowed values: `discountable`, `all`,
"groupings": [string] // Grouping values for aggregating costs on the FinancialCommitmentReport. Group by up to 100 fields. Valid groupings: cost_type, provider, commitment_type, commitment_id, service, resource_account_id, provider_account_id, region, cost_category, cost_sub_category, instance_type, tag:label_name
}
```
#### Responses
**200**: OK
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/financialcommitmentreports/update-financial-commitment-report](https://docs.vantage.sh/api/financialcommitmentreports/update-financial-commitment-report)
***
### GET /financial\_commitment\_reports/{financial_commitment_report_token}/costs
**Get costs for financial commitment report**
Return costs for a FinancialCommitmentReport.
#### Path Parameters
* **financial\_commitment\_report\_token** (path) (string) - **Required**
#### Query Parameters
* **start\_date** (string (date)) - Optional: First date you would like to filter costs from, inclusive. YYYY-MM-DD formatted.
* Example: `2024-03-01`
* **end\_date** (string (date)) - Optional: Last date you would like to filter costs to, inclusive. YYYY-MM-DD formatted.
* Example: `2024-03-31`
* **date\_bin** (string) - Optional: The date bin of the costs. Defaults to the report's configured date bucket. Hourly costs are limited to 14 days.
* Allowed values: `hour`, `day`, `week`, `month`, `quarter`
* **groupings** (array) - Optional: Group the results by up to 100 fields. Valid groupings: cost\_type, provider, commitment\_type, commitment\_id, service, resource\_account\_id, provider\_account\_id, region, cost\_category, cost\_sub\_category, instance\_type, tag:label\_name. Serialize as a CSV query parameter: groupings=cost\_type,service. Repeated parameters (groupings\[]=cost\_type\&groupings\[]=service) are also accepted.
* **filter** (string) - Optional: The VQL filter to apply to the costs. Overrides the report's saved filter.
* **on\_demand\_costs\_scope** (string) - Optional: The scope for the costs. Possible values: discountable, all.
* Allowed values: `discountable`, `all`
* **order** (string) - Optional: Whether to order costs by date in an ascending or descending manner.
* Allowed values: `asc`, `desc`
* Default: `desc`
* **limit** (integer (int32)) - Optional: The number of cost rows to return, not the number of date buckets. The maximum is 5000.
* Default: `2500`
* **page** (integer (int32)) - Optional: The page of results to return.
* Default: `1`
#### Responses
**200**: OK
**400**: BadRequest
**402**: PaymentRequired
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/financialcommitmentreports/get-costs-for-financial-commitment-report](https://docs.vantage.sh/api/financialcommitmentreports/get-costs-for-financial-commitment-report)
***
## FinancialCommitments
### GET /financial\_commitments
**Get all financial commitments**
Return all FinancialCommitments.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/financialcommitments/get-all-financial-commitments](https://docs.vantage.sh/api/financialcommitments/get-all-financial-commitments)
***
## Folders
### GET /folders
**Get all folders**
Return all Folders for CostReports.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **type** (string) - Optional: Filter by folder type.
* Allowed values: `CostFolder`, `ProviderResourceFolder`
* **q** (string) - Optional: Search folders by title.
* **workspace\_token** (string) - Optional: The workspace token of the folders to return.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/folders/get-all-folders](https://docs.vantage.sh/api/folders/get-all-folders)
***
### POST /folders
**Create folder**
Create a Folder for CostReports.
#### Request Body
```json theme={null}
{
"title": string // required // The title of the Folder,
"parent_folder_token": string // The token of the parent Folder,
"saved_filter_tokens": [string] // The tokens of the SavedFilters to apply to any Cost Report contained within the Folder,
"workspace_token": string // The token of the Workspace to add the Folder to. Ignored if 'parent_folder_token' is set. Required if the API token is associated with multiple Workspaces,
"type": string // The type of the Folder. Allowed values: `CostFolder`, `ProviderResourceFolder`
}
```
#### Responses
**201**: Created
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/folders/create-folder](https://docs.vantage.sh/api/folders/create-folder)
***
### DELETE /folders/{folder_token}
**Delete folder**
Delete a Folder for CostReports.
#### Path Parameters
* **folder\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/folders/delete-folder](https://docs.vantage.sh/api/folders/delete-folder)
***
### GET /folders/{folder_token}
**Get folder by token**
Return a specific Folder for CostReports.
#### Path Parameters
* **folder\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/folders/get-folder-by-token](https://docs.vantage.sh/api/folders/get-folder-by-token)
***
### PUT /folders/{folder_token}
**Update folder**
Update a Folder for CostReports.
#### Path Parameters
* **folder\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the Folder,
"parent_folder_token": string // The token of the parent Folder,
"saved_filter_tokens": [string] // The tokens of the SavedFilters to apply to any Cost Report contained within the Folder
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/folders/update-folder](https://docs.vantage.sh/api/folders/update-folder)
***
## Integrations
### GET /integrations
**Get all integrations**
Return all Integrations.
#### Query Parameters
* **provider** (string) - Optional: Query by provider name to list all Integrations for a specific provider.
* Allowed values: `aws`, `azure`, `gcp`, `snowflake`, `databricks`, `mongo`, `datadog`, `fastly`, `new_relic`, `opencost`, `open_ai`, `oracle`, `confluent`, `planetscale`, `coralogix`, `kubernetes`, `custom_provider`, `github`, `linode`, `grafana`, `clickhouse`, `temporal`, `twilio`, `azure_csp`, `kubernetes_agent`, `anthropic`, `anyscale`, `cursor`, `elastic`, `vercel`, `redis_cloud`, `circle_ci`, `modal`, `eleven_labs`, `baseten`, `cloudflare`, `fireworks_ai`, `cartesia`, `depot`, `xai`, `digital_ocean`, `together_ai`, `coreweave`, `devin`, `openrouter`, `deepgram`, `crusoe`, `sentry_billing`, `ramp`
* **account\_identifier** (string) - Optional: Query by account identifier to list all Integrations that match a specific account. For Azure, this is the subscription ID. Must include provider when using this parameter.
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The number of results to return. The maximum is 1000.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/integrations/get-all-integrations](https://docs.vantage.sh/api/integrations/get-all-integrations)
***
### POST /integrations/azure
**Create Azure integration**
Create an Azure Integration
#### Request Body
```json theme={null}
{
"tenant": string // required // Azure AD Tenant ID,
"app_id": string // required // Service Principal Application ID,
"password": string // required // Service Principal Password,
"billing_account_id": string // Microsoft Customer Agreement (MCA) or Enterprise Agreement (EA) billing account ID. Must not contain whitespace
}
```
#### Responses
**201**: Created
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/integrations/create-azure-integration](https://docs.vantage.sh/api/integrations/create-azure-integration)
***
### POST /integrations/custom\_provider
**Create custom provider integration**
Create a Custom Provider Integration
#### Request Body
```json theme={null}
{
"name": string // required // Name of the Custom Provider Integration,
"description": string // Description of the Custom Provider Integration
}
```
#### Responses
**201**: Created
**400**: BadRequest
**403**: Forbidden
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/integrations/create-custom-provider-integration](https://docs.vantage.sh/api/integrations/create-custom-provider-integration)
***
### POST /integrations/gcp
**Create GCP integration**
Create a GCP Integration
#### Request Body
```json theme={null}
{
"billing_account_id": string // required // GCP billing account ID,
"project_id": string // required // GCP project ID,
"dataset_name": string // required // BigQuery dataset name
}
```
#### Responses
**201**: Created
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/integrations/create-gcp-integration](https://docs.vantage.sh/api/integrations/create-gcp-integration)
***
### POST /integrations/twilio
**Create Twilio integration**
Create a Twilio Integration
#### Request Body
```json theme={null}
{
"api_key": string // required // Twilio API key SID,
"api_secret": string // required // Twilio API key secret,
"account_sid": string // required // Twilio account SID,
"friendly_account_name": string // required // Name for this Twilio account in Vantage,
"description": string // required // Description of the integration,
"is_oauth": boolean // When true, api_key and api_secret are an OAuth client id and secret
}
```
#### Responses
**201**: Created
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/integrations/create-twilio-integration](https://docs.vantage.sh/api/integrations/create-twilio-integration)
***
### DELETE /integrations/{integration_token}
**Delete integration**
Delete an Integration.
#### Path Parameters
* **integration\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/integrations/delete-integration](https://docs.vantage.sh/api/integrations/delete-integration)
***
### GET /integrations/{integration_token}
**Get integration by token**
Return an Integration.
#### Path Parameters
* **integration\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/integrations/get-integration-by-token](https://docs.vantage.sh/api/integrations/get-integration-by-token)
***
### PUT /integrations/{integration_token}
**Update integration**
Update an Integration.
#### Path Parameters
* **integration\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"workspace_tokens": [string] // The Workspace tokens to associate to the Integration
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/integrations/update-integration](https://docs.vantage.sh/api/integrations/update-integration)
***
### GET /integrations/{integration_token}/costs
**Get all user costs uploads**
List UserCostUploads.
#### Path Parameters
* **integration\_token** (path) (string) - **Required**
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/integrations/get-all-user-costs-uploads](https://docs.vantage.sh/api/integrations/get-all-user-costs-uploads)
***
### POST /integrations/{integration_token}/costs.csv
**Upload custom provider costs**
Create UserCostsUpload via CSV for a Custom Provider Integration.
#### Path Parameters
* **integration\_token** (path) (string) - **Required**
#### Responses
**201**: Created
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/integrations/upload-custom-provider-costs](https://docs.vantage.sh/api/integrations/upload-custom-provider-costs)
***
### DELETE /integrations/{integration_token}/costs/{user_costs_upload_token}
**Delete user costs upload**
Delete a UserCostsUpload.
#### Path Parameters
* **integration\_token** (path) (string) - **Required**
* **user\_costs\_upload\_token** (path) (string) - **Required**: Token of the UserCostsUpload to delete.
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/integrations/delete-user-costs-upload](https://docs.vantage.sh/api/integrations/delete-user-costs-upload)
***
## Invoices
### GET /invoices
**Get all invoices**
Returns a list of invoices (MSP invoicing required).
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **managed\_account\_token** (string) - Optional: Filter invoices by managed account token (MSP accounts only)
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/invoices/get-all-invoices](https://docs.vantage.sh/api/invoices/get-all-invoices)
***
### POST /invoices
**Create invoice**
Create an invoice (MSP accounts only).
#### Request Body
```json theme={null}
{
"billing_period_start": string // required // Start date of billing period (YYYY-MM-DD),
"billing_period_end": string // required // End date of billing period (YYYY-MM-DD),
"account_token": string // required // Token of the managed account to invoice
}
```
#### Responses
**201**: Created
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/invoices/create-invoice](https://docs.vantage.sh/api/invoices/create-invoice)
***
### GET /invoices/{invoice_token}
**Get invoice by token**
Return an invoice.
#### Path Parameters
* **invoice\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/invoices/get-invoice-by-token](https://docs.vantage.sh/api/invoices/get-invoice-by-token)
***
### GET /invoices/{invoice_token}/cost\_report
**Get cost report URL**
Get cost report URL for invoice period.
#### Path Parameters
* **invoice\_token** (path) (string) - **Required**
#### Responses
**200**: Get cost report URL for invoice period.
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/invoices/get-cost-report-url](https://docs.vantage.sh/api/invoices/get-cost-report-url)
***
### POST /invoices/{invoice_token}/download
**Get invoice file**
Download invoice file (PDF or CSV).
#### Path Parameters
* **invoice\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"file_type": string // required // Type of file to download (pdf or csv). Allowed values: `pdf`, `csv`
}
```
#### Responses
**200**: Returns download URL for the invoice file
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/invoices/get-invoice-file](https://docs.vantage.sh/api/invoices/get-invoice-file)
***
### POST /invoices/{invoice_token}/regenerate
**Regenerate invoice**
Regenerate an existing invoice (MSP accounts only).
#### Path Parameters
* **invoice\_token** (path) (string) - **Required**
#### Responses
**200**: Invoice regeneration started
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/invoices/regenerate-invoice](https://docs.vantage.sh/api/invoices/regenerate-invoice)
***
### POST /invoices/{invoice_token}/send
**Send invoice**
Send invoice via email.
#### Path Parameters
* **invoice\_token** (path) (string) - **Required**
#### Responses
**200**: Invoice sent successfully
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/invoices/send-invoice](https://docs.vantage.sh/api/invoices/send-invoice)
***
### POST /invoices/{invoice_token}/send\_and\_approve
**Send and approve invoice**
Send and approve invoice via email (MSP accounts only).
#### Path Parameters
* **invoice\_token** (path) (string) - **Required**
#### Responses
**200**: Invoice approved and sent successfully
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/invoices/send-and-approve-invoice](https://docs.vantage.sh/api/invoices/send-and-approve-invoice)
***
## KubernetesEfficiencyReports
### GET /kubernetes\_efficiency\_reports
**Get all Kubernetes efficiency reports**
Return all KubernetesEfficiencyReports.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **workspace\_token** (string) - Optional: Filter by workspace token.
* **q** (string) - Optional: Search Kubernetes efficiency reports by title.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/kubernetesefficiencyreports/get-all-kubernetes-efficiency-reports](https://docs.vantage.sh/api/kubernetesefficiencyreports/get-all-kubernetes-efficiency-reports)
***
### POST /kubernetes\_efficiency\_reports
**Create Kubernetes efficiency report**
Create a KubernetesEfficiencyReport.
#### Request Body
```json theme={null}
{
"workspace_token": string // required // The Workspace in which the KubernetesEfficiencyReport will be created,
"title": string // required // The title of the KubernetesEfficiencyReport,
"filter": string // The filter query language to apply to the KubernetesEfficiencyReport. Additional documentation available at https://docs.vantage.sh/vql,
"start_date": string // The start date of the KubernetesEfficiencyReport. ISO 8601 Formatted. Incompatible with 'date_interval' parameter,
"end_date": string // The end date of the KubernetesEfficiencyReport. ISO 8601 Formatted. Incompatible with 'date_interval' parameter,
"date_interval": string // The date interval of the KubernetesEfficiencyReport. Incompatible with 'start_date' and 'end_date' parameters. Defaults to 'this_month' if start_date and end_date are not provided. Allowed values: `this_month`, `last_7_days`, `last_30_days`, `last_month`, `last_3_months`, `last_6_months`, `custom`, `last_12_months`, `last_24_months`, `last_36_months`, `next_month`, `next_3_months`, `next_6_months`, `next_12_months`, `year_to_date`, `last_3_days`, `last_14_days`,
"aggregated_by": string // The column by which the costs are aggregated. Allowed values: `idle_cost`, `amount`, `cost_efficiency`,
"date_bucket": string // The date bucket of the KubernetesEfficiencyReport. Allowed values: `day`, `week`, `month`, `quarter`,
"groupings": [string] // Grouping values for aggregating costs on the KubernetesEfficiencyReport. Group by up to 100 fields. Valid groupings: cluster_id, namespace, region, labeled, category, pod, label:label_name
}
```
#### Responses
**201**: Created
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/kubernetesefficiencyreports/create-kubernetes-efficiency-report](https://docs.vantage.sh/api/kubernetesefficiencyreports/create-kubernetes-efficiency-report)
***
### POST /kubernetes\_efficiency\_reports/data\_exports
**Generate Kubernetes efficiency data export**
Generate a DataExport of Kubernetes efficiency data.
#### Query Parameters
* **groupings** (array) - Optional: Group the results by up to 100 fields. Valid groupings: cluster\_id, namespace, region, labeled, category, pod, label:label\_name.
#### Request Body
```json theme={null}
{
"kubernetes_efficiency_report_token": string // The KubernetesEfficiencyReport token. If not provided, the default report for the workspace will be used,
"filter": string // The filter query language to apply to the KubernetesEfficiencyReport. Additional documentation available at https://docs.vantage.sh/vql,
"workspace_token": string // The token of the Workspace to export data from. Ignored if 'kubernetes_efficiency_report_token' is set. Required if the API token is associated with multiple Workspaces,
"start_date": string // First date you would like to filter data from. ISO 8601 formatted,
"end_date": string // Last date you would like to filter data to. ISO 8601 formatted,
"date_bin": string // The date bin of the data. Defaults to the report's default or day. Allowed values: `day`, `week`, `month`, `quarter`
}
```
#### Responses
**202**: The data export has been queued and will be available at the location specified in the Location header.
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/kubernetesefficiencyreports/generate-kubernetes-efficiency-data-export](https://docs.vantage.sh/api/kubernetesefficiencyreports/generate-kubernetes-efficiency-data-export)
***
### DELETE /kubernetes\_efficiency\_reports/{kubernetes_efficiency_report_token}
**Delete Kubernetes efficiency report**
Delete a KubernetesEfficiencyReport.
#### Path Parameters
* **kubernetes\_efficiency\_report\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/kubernetesefficiencyreports/delete-kubernetes-efficiency-report](https://docs.vantage.sh/api/kubernetesefficiencyreports/delete-kubernetes-efficiency-report)
***
### GET /kubernetes\_efficiency\_reports/{kubernetes_efficiency_report_token}
**Get Kubernetes efficiency report by token**
Return a KubernetesEfficiencyReport.
#### Path Parameters
* **kubernetes\_efficiency\_report\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/kubernetesefficiencyreports/get-kubernetes-efficiency-report-by-token](https://docs.vantage.sh/api/kubernetesefficiencyreports/get-kubernetes-efficiency-report-by-token)
***
### PUT /kubernetes\_efficiency\_reports/{kubernetes_efficiency_report_token}
**Update Kubernetes efficiency report**
Update a KubernetesEfficiencyReport.
#### Path Parameters
* **kubernetes\_efficiency\_report\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the KubernetesEfficiencyReport,
"filter": string // The filter query language to apply to the KubernetesEfficiencyReport. Additional documentation available at https://docs.vantage.sh/vql,
"start_date": string // The start date of the KubernetesEfficiencyReport. ISO 8601 Formatted. Incompatible with 'date_interval' parameter,
"end_date": string // The end date of the KubernetesEfficiencyReport. ISO 8601 Formatted. Incompatible with 'date_interval' parameter,
"date_interval": string // The date interval of the KubernetesEfficiencyReport. Incompatible with 'start_date' and 'end_date' parameters. Defaults to 'this_month' if start_date and end_date are not provided. Allowed values: `this_month`, `last_7_days`, `last_30_days`, `last_month`, `last_3_months`, `last_6_months`, `custom`, `last_12_months`, `last_24_months`, `last_36_months`, `next_month`, `next_3_months`, `next_6_months`, `next_12_months`, `year_to_date`, `last_3_days`, `last_14_days`,
"aggregated_by": string // The column by which the costs are aggregated. Allowed values: `idle_cost`, `amount`, `cost_efficiency`,
"date_bucket": string // The date bucket of the KubernetesEfficiencyReport. Allowed values: `day`, `week`, `month`, `quarter`,
"groupings": [string] // Grouping values for aggregating costs on the KubernetesEfficiencyReport. Group by up to 100 fields. Valid groupings: cluster_id, namespace, region, labeled, category, pod, label:label_name
}
```
#### Responses
**200**: OK
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/kubernetesefficiencyreports/update-kubernetes-efficiency-report](https://docs.vantage.sh/api/kubernetesefficiencyreports/update-kubernetes-efficiency-report)
***
### GET /kubernetes\_efficiency\_reports/{kubernetes_efficiency_report_token}/costs
**Get costs for Kubernetes efficiency report**
Return costs for a KubernetesEfficiencyReport.
#### Path Parameters
* **kubernetes\_efficiency\_report\_token** (path) (string) - **Required**
#### Query Parameters
* **start\_date** (string (date)) - Optional: First date to query costs from, inclusive. YYYY-MM-DD formatted.
* Example: `2026-09-01`
* **end\_date** (string (date)) - Optional: Last date to query costs through, inclusive. YYYY-MM-DD formatted.
* Example: `2026-09-30`
* **date\_bin** (string) - Optional: The date bin for the costs. Defaults to the report's configured date bucket.
* Allowed values: `day`, `week`, `month`, `quarter`
* **groupings** (array) - Optional: Group the cost rows by up to 100 fields. Valid groupings: cluster\_id, namespace, region, labeled, category, pod, label:label\_name.
* **filter** (string) - Optional: The VQL filter to apply to the costs. Overrides the report's saved filter.
* **order** (string) - Optional: Whether to order cost rows by date ascending or descending.
* Allowed values: `asc`, `desc`
* Default: `desc`
* **page** (integer (int32)) - Optional: The page of cost rows to return.
* Default: `1`
* **limit** (integer (int32)) - Optional: The number of cost rows to return. The maximum is 2500.
* Default: `500`
#### Responses
**200**: OK
**400**: BadRequest
**402**: PaymentRequired
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/kubernetesefficiencyreports/get-costs-for-kubernetes-efficiency-report](https://docs.vantage.sh/api/kubernetesefficiencyreports/get-costs-for-kubernetes-efficiency-report)
***
## ManagedAccounts
### GET /managed\_accounts
**Get all managed accounts**
Returns a list of managed accounts.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/managedaccounts/get-all-managed-accounts](https://docs.vantage.sh/api/managedaccounts/get-all-managed-accounts)
***
### POST /managed\_accounts
**Create managed account**
Create a Managed Account.
#### Request Body
```json theme={null}
{
"name": string // required // The name of the Managed Account,
"contact_email": string // required // The contact email address for the Managed Account,
"access_credential_tokens": [string] // Access Credential (aka Integrations) tokens to assign to the Managed Account,
"billing_rule_tokens": [string] // Billing Rule tokens to assign to the Managed Account, in their desired execution order. Tokens must be ordered by execution group: AWS transforms, then COST inserts, then COST transforms, then monthly post-transform inserts. Within a group any order is accepted and persisted as-is. Submitting a list whose cross-group ordering does not match the pipeline returns a 400.Existing rules with apply_to_all enabled will be added implicity to the end of their execution group,
"email_domain": string // Email domain to associate with this Managed Account for SSO
}
```
#### Responses
**201**: Created
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/managedaccounts/create-managed-account](https://docs.vantage.sh/api/managedaccounts/create-managed-account)
***
### DELETE /managed\_accounts/{managed_account_token}
**Delete managed account**
Delete a Managed Account.
#### Path Parameters
* **managed\_account\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/managedaccounts/delete-managed-account](https://docs.vantage.sh/api/managedaccounts/delete-managed-account)
***
### GET /managed\_accounts/{managed_account_token}
**Get managed account by token**
Return a Managed Account.
#### Path Parameters
* **managed\_account\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/managedaccounts/get-managed-account-by-token](https://docs.vantage.sh/api/managedaccounts/get-managed-account-by-token)
***
### PUT /managed\_accounts/{managed_account_token}
**Update managed account**
Update a Managed Account.
#### Path Parameters
* **managed\_account\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"name": string // The name of the Managed Account,
"contact_email": string // The contact email address for the Managed Account,
"access_credential_tokens": [string] // Access Credential (aka Integrations) tokens to assign to the Managed Account,
"billing_rule_tokens": [string] // Billing Rule tokens to assign to the Managed Account, in their desired execution order. Tokens must be ordered by execution group: AWS transforms, then COST inserts, then COST transforms, then monthly post-transform inserts. Within a group any order is accepted and persisted as-is. Submitting a list whose cross-group ordering does not match the pipeline returns a 400,
"email_domain": string // Email domain to associate with this Managed Account for SSO,
"msp_billing_profile_token": string // Token of the MSP billing profile to use for this managed account (MSP invoicing accounts only),
"payment_terms_days": integer // Number of days until payment is due after invoice date (MSP invoicing accounts only). Defaults to 10,
"include_managed_account_integrations": boolean // Whether to include managed account's own integrations in invoice cost calculations (MSP invoicing accounts only). Defaults to false,
"billing_information_attributes": { // Billing address and contact information (MSP invoicing accounts only)
"id": integer,
"token": string,
"company_name": string // Company name for billing,
"country_code": string // ISO country code,
"address_line_1": string // First line of billing address,
"address_line_2": string // Second line of billing address,
"city": string // City for billing address,
"state": string // State or province for billing address,
"postal_code": string // Postal or ZIP code,
"billing_email": [string] // Array of billing email addresses
},
"business_information_attributes": { // Business information and custom fields (MSP invoicing accounts only)
"id": integer,
"token": string,
"metadata": { // Business metadata including custom fields
"custom_fields": [ // Array of custom field objects
{
"name": string // Custom field name,
"value": string // Custom field value
}
]
}
}
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/managedaccounts/update-managed-account](https://docs.vantage.sh/api/managedaccounts/update-managed-account)
***
### GET /managed\_accounts/{managed_account_token}/integrations/{access_credential_token}
**Get managed account integration**
Returns the Integration delegated to this Managed Account from the Access Credential named in the path, along with the provider account identifiers it imports. Delegate an Access Credential to a Managed Account with access\_credential\_tokens before calling this.
#### Path Parameters
* **managed\_account\_token** (path) (string) - **Required**
* **access\_credential\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/managedaccounts/get-managed-account-integration](https://docs.vantage.sh/api/managedaccounts/get-managed-account-integration)
***
### PUT /managed\_accounts/{managed_account_token}/integrations/{access_credential_token}
**Update managed account integration**
Replaces the provider account identifiers a delegated Integration imports. An empty array applies no filter, so every provider account the Access Credential can see is imported. Identifiers are only accepted for providers that support scoping a delegation. Azure CSP uses subscription ids and GCP uses project ids. Stop delegating an Integration by removing its token from access\_credential\_tokens on the Managed Account.
#### Path Parameters
* **managed\_account\_token** (path) (string) - **Required**
* **access\_credential\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"provider_account_identifiers": [string] // required // The provider account identifiers this delegated Integration should import, replacing the current list. For Azure CSP these are subscription ids and for GCP these are project ids. An empty array applies no filter
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/managedaccounts/update-managed-account-integration](https://docs.vantage.sh/api/managedaccounts/update-managed-account-integration)
***
### DELETE /managed\_accounts/{managed_account_token}/sso\_connection
**Delete SSO connection for managed account**
Delete SSO connection for a Managed Account.
#### Path Parameters
* **managed\_account\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/managedaccounts/delete-sso-connection-for-managed-account](https://docs.vantage.sh/api/managedaccounts/delete-sso-connection-for-managed-account)
***
### POST /managed\_accounts/{managed_account_token}/sso\_connection
**Configure SSO for managed account**
Configure SSO for a Managed Account.
#### Path Parameters
* **managed\_account\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"type": string // required // The type of SSO connection. Currently supported: saml. Allowed values: `saml`,
"saml_metadata_url": string // The SAML metadata URL for the identity provider. Required when type is saml,
"additional_domains": [string] // Additional email domains to associate with this SSO configuration. The account's SSO domain is always included
}
```
#### Responses
**201**: Created
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/managedaccounts/configure-sso-for-managed-account](https://docs.vantage.sh/api/managedaccounts/configure-sso-for-managed-account)
***
### PUT /managed\_accounts/{managed_account_token}/sso\_connection
**Update SSO configuration for managed account**
Update SSO configuration for a Managed Account.
#### Path Parameters
* **managed\_account\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"saml_metadata_url": string // The SAML metadata URL for the identity provider,
"additional_domains": [string] // Additional email domains to associate with this SSO configuration. Replaces existing additional domains. The account's SSO domain is always preserved
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/managedaccounts/update-sso-configuration-for-managed-account](https://docs.vantage.sh/api/managedaccounts/update-sso-configuration-for-managed-account)
***
## Me
### GET /me
**Get authenticated user info**
Get information about the authenticated BearerToken.
#### Responses
**200**: General information about the user.
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/me/get-authenticated-user-info](https://docs.vantage.sh/api/me/get-authenticated-user-info)
***
### PUT /me
**Update authenticated user**
Update the authenticated User.
#### Request Body
```json theme={null}
{
"default_dashboard_token": string // The token of a Dashboard to set as the User default. Send null to clear
}
```
#### Responses
**200**: OK
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/me/update-authenticated-user](https://docs.vantage.sh/api/me/update-authenticated-user)
***
## NetworkFlowLogs
### GET /network\_flow\_logs
**Get network flow logs**
Return aggregated Network Flow Logs for a saved report or ad hoc VQL query.
#### Query Parameters
* **network\_flow\_report\_token** (string) - Optional
* **workspace\_token** (string) - Optional
* **filter** (string) - Optional
* **date\_interval** (string) - Optional
* Allowed values: `last_3_days`, `last_7_days`, `last_14_days`, `last_30_days`
* **start\_date** (string (date)) - Optional
* **end\_date** (string (date)) - Optional
* **groupings** (array) - Optional
* **flow\_direction** (string) - Optional
* Allowed values: `all`, `ingress`, `egress`
* **flow\_weight** (string) - Optional
* Allowed values: `costs`, `bytes`
* **page** (integer (int32)) - Optional
* Default: `1`
* **limit** (integer (int32)) - Optional
* Default: `100`
#### Responses
**200**: OK
**400**: BadRequest
**402**: PaymentRequired
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/networkflowlogs/get-network-flow-logs](https://docs.vantage.sh/api/networkflowlogs/get-network-flow-logs)
***
## NetworkFlowReports
### GET /network\_flow\_reports
**Get all network flow reports**
Return all NetworkFlowReports.
#### Query Parameters
* **q** (string) - Optional: A search query to filter NetworkFlowReports by title.
* **workspace\_token** (string) - Optional: Filter by workspace token.
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/networkflowreports/get-all-network-flow-reports](https://docs.vantage.sh/api/networkflowreports/get-all-network-flow-reports)
***
### POST /network\_flow\_reports
**Create network flow report**
Create a NetworkFlowReport.
#### Request Body
```json theme={null}
{
"workspace_token": string // required // The Workspace in which the NetworkFlowReport will be created,
"title": string // required // The title of the NetworkFlowReport,
"filter": string // The filter query language to apply to the NetworkFlowReport. Additional documentation available at https://docs.vantage.sh/vql,
"start_date": string // The start date of a custom NetworkFlowReport. YYYY-MM-DD formatted,
"end_date": string // The end date of a custom NetworkFlowReport. YYYY-MM-DD formatted,
"date_interval": string // The date interval of the NetworkFlowReport. Dates are used only for the 'custom' interval. Defaults to 'last_7_days'. Allowed values: `last_3_days`, `last_7_days`, `last_14_days`, `last_30_days`, `custom`,
"groupings": [string] // Grouping values for aggregating data on the NetworkFlowReport. Valid groupings: account_id, az_id, dstaddr, dsthostname, flow_direction, interface_id, instance_id, peer_resource_uuid, peer_account_id, peer_vpc_id, peer_region, peer_az_id, peer_subnet_id, peer_interface_id, peer_instance_id, region, resource_uuid, srcaddr, srchostname, subnet_id, traffic_category, traffic_path, vpc_id,
"flow_direction": string // The flow direction of the NetworkFlowReport. Allowed values: `all`, `ingress`, `egress`,
"flow_weight": string // The dimension by which the logs in the report are sorted. Defaults to costs. Allowed values: `costs`, `bytes`
}
```
#### Responses
**201**: Created
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/networkflowreports/create-network-flow-report](https://docs.vantage.sh/api/networkflowreports/create-network-flow-report)
***
### DELETE /network\_flow\_reports/{network_flow_report_token}
**Delete network flow report**
Delete a NetworkFlowReport.
#### Path Parameters
* **network\_flow\_report\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/networkflowreports/delete-network-flow-report](https://docs.vantage.sh/api/networkflowreports/delete-network-flow-report)
***
### GET /network\_flow\_reports/{network_flow_report_token}
**Get network flow report by token**
Return a NetworkFlowReport.
#### Path Parameters
* **network\_flow\_report\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/networkflowreports/get-network-flow-report-by-token](https://docs.vantage.sh/api/networkflowreports/get-network-flow-report-by-token)
***
### PUT /network\_flow\_reports/{network_flow_report_token}
**Update network flow report**
Update a NetworkFlowReport.
#### Path Parameters
* **network\_flow\_report\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the NetworkFlowReport,
"filter": string // The filter query language to apply to the NetworkFlowReport. Additional documentation available at https://docs.vantage.sh/vql,
"start_date": string // The start date of a custom NetworkFlowReport. YYYY-MM-DD formatted,
"end_date": string // The end date of a custom NetworkFlowReport. YYYY-MM-DD formatted,
"date_interval": string // The date interval of the NetworkFlowReport. Dates are used only for the 'custom' interval. Defaults to 'last_7_days'. Allowed values: `last_3_days`, `last_7_days`, `last_14_days`, `last_30_days`, `custom`,
"groupings": [string] // Grouping values for aggregating data on the NetworkFlowReport. Valid groupings: account_id, az_id, dstaddr, dsthostname, flow_direction, interface_id, instance_id, peer_resource_uuid, peer_account_id, peer_vpc_id, peer_region, peer_az_id, peer_subnet_id, peer_interface_id, peer_instance_id, region, resource_uuid, srcaddr, srchostname, subnet_id, traffic_category, traffic_path, vpc_id,
"flow_direction": string // The flow direction of the NetworkFlowReport. Allowed values: `all`, `ingress`, `egress`,
"flow_weight": string // The dimension by which the logs in the report are sorted. Defaults to costs. Allowed values: `costs`, `bytes`
}
```
#### Responses
**200**: OK
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/networkflowreports/update-network-flow-report](https://docs.vantage.sh/api/networkflowreports/update-network-flow-report)
***
## Ping
### GET /ping
This is a health check endpoint that can be used to determine Vantage API healthiness. It will return 200 if everything is running smoothly.
#### Responses
**200**: This is a health check endpoint that can be used to determine Vantage API healthiness. It will return 200 if everything is running smoothly.
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/ping/](https://docs.vantage.sh/api/ping/)
***
## Prices
### GET /products
**Get all products**
Return available Products for a Service. For example, with a Provider of AWS and a Service of EC2, Products will be a list of all EC2 Instances. By default, this endpoint returns all Products across all Services and Providers but has optional query parameters for filtering listed below.
#### Query Parameters
* **provider\_id** (string) - Optional: Query by Provider to list all Products across all Services for a Provider. e.g. aws
* **service\_id** (string) - Optional: Query by Service to list all Products for a specific provider service. e.g. aws-ec2
* **name** (string) - Optional: Query by name of the Product to see a list of products which match that name. e.g. m5a.16xlarge
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/prices/get-all-products](https://docs.vantage.sh/api/prices/get-all-products)
***
### GET /products/{id}
**Get product by ID**
Return a product
#### Path Parameters
* **id** (path) (string) - **Required**
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/prices/get-product-by-id](https://docs.vantage.sh/api/prices/get-product-by-id)
***
### GET /products/{product_id}/prices
**Get prices for a product**
Return available Prices across all Regions for a Product.
#### Path Parameters
* **product\_id** (path) (string) - **Required**
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/prices/get-prices-for-a-product](https://docs.vantage.sh/api/prices/get-prices-for-a-product)
***
### GET /products/{product_id}/prices/{id}
**Get price by ID**
Returns a price
#### Path Parameters
* **product\_id** (path) (string) - **Required**
* **id** (path) (string) - **Required**
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/prices/get-price-by-id](https://docs.vantage.sh/api/prices/get-price-by-id)
***
## RecommendationViews
### GET /recommendation\_views
**Get all recommendation views**
Return all RecommendationViews.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **workspace\_token** (string) - Optional: Filter by workspace token.
* **q** (string) - Optional: Search recommendation views by title.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/recommendationviews/get-all-recommendation-views](https://docs.vantage.sh/api/recommendationviews/get-all-recommendation-views)
***
### POST /recommendation\_views
**Create recommendation view**
Create a RecommendationView.
#### Request Body
```json theme={null}
{
"title": string // required // The title of the RecommendationView,
"workspace_token": string // required // The Workspace to associate the RecommendationView with,
"provider_ids": [string] // Filter by one or more providers (e.g. aws, gcp, azure, kubernetes, datadog),
"billing_account_ids": [string] // Filter by billing account identifiers,
"account_ids": [string] // Filter by cloud account identifiers,
"regions": [string] // Filter by region slugs (e.g. us-east-1, eastus, asia-east1),
"types": [string] // Filter by one or more recommendation type slugs,
"tag_key": string // Filter by tag key (must be used with tag_value),
"tag_value": string // Filter by tag value (requires tag_key),
"start_date": string // Filter recommendations created on/after this YYYY-MM-DD date,
"end_date": string // Filter recommendations created on/before this YYYY-MM-DD date,
"min_savings": number // Filter recommendations with at least this amount of potential savings
}
```
#### Responses
**201**: Created
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/recommendationviews/create-recommendation-view](https://docs.vantage.sh/api/recommendationviews/create-recommendation-view)
***
### DELETE /recommendation\_views/{recommendation_view_token}
**Delete recommendation view**
Delete a RecommendationView.
#### Path Parameters
* **recommendation\_view\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/recommendationviews/delete-recommendation-view](https://docs.vantage.sh/api/recommendationviews/delete-recommendation-view)
***
### GET /recommendation\_views/{recommendation_view_token}
**Get recommendation view by token**
Return a specific RecommendationView.
#### Path Parameters
* **recommendation\_view\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/recommendationviews/get-recommendation-view-by-token](https://docs.vantage.sh/api/recommendationviews/get-recommendation-view-by-token)
***
### PUT /recommendation\_views/{recommendation_view_token}
**Update recommendation view**
Update a RecommendationView.
#### Path Parameters
* **recommendation\_view\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the RecommendationView,
"provider_ids": [string] // Filter by one or more providers (e.g. aws, gcp, azure, kubernetes, datadog),
"billing_account_ids": [string] // Filter by billing account identifiers,
"account_ids": [string] // Filter by cloud account identifiers,
"regions": [string] // Filter by region slugs (e.g. us-east-1, eastus, asia-east1),
"types": [string] // Filter by one or more recommendation type slugs,
"tag_key": string // Filter by tag key (must be used with tag_value),
"tag_value": string // Filter by tag value (requires tag_key),
"start_date": string // Filter recommendations created on/after this YYYY-MM-DD date,
"end_date": string // Filter recommendations created on/before this YYYY-MM-DD date,
"min_savings": number // Filter recommendations with at least this amount of potential savings
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/recommendationviews/update-recommendation-view](https://docs.vantage.sh/api/recommendationviews/update-recommendation-view)
***
## Recommendations
### GET /recommendations
**Get all recommendations**
Return all Recommendations. Use the `type` query parameter with a fuzzy fragment to filter recommendation type case-insensitively (for example: aws, aws:ec2, aws:ec2:rightsizing).
#### Query Parameters
* **provider\_ids** (array) - Optional: Filter by one or more providers. Requires workspace\_token.
* **billing\_account\_ids** (array) - Optional: Filter by billing account identifiers. Requires workspace\_token.
* **account\_ids** (array) - Optional: Filter by account identifiers. Requires workspace\_token.
* **regions** (array) - Optional: Filter by region slugs (e.g. us-east-1, eastus, asia-east1). Requires workspace\_token.
* **tag\_key** (string) - Optional: Filter by tag key (must be used with tag\_value). Requires workspace\_token.
* **tag\_value** (string) - Optional: Filter by tag value (requires tag\_key). Requires workspace\_token.
* **start\_date** (string) - Optional: Filter recommendations created on/after this YYYY-MM-DD date. Requires workspace\_token.
* **end\_date** (string) - Optional: Filter recommendations created on/before this YYYY-MM-DD date. Requires workspace\_token.
* **status** (string) - Optional: Filter by status.
* Allowed values: `active`, `archived`
* **min\_savings** (number (float)) - Optional: Filter by recommendations whose potential savings are greater than or equal to this amount, in the workspace's currency. Requires workspace\_token.
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The number of results to return. The maximum is 1000.
* **workspace\_token** (string) - Optional: Filter by workspace.
* **provider\_account\_id** (string) - Optional: Filter by provider account id (AWS account, Azure subscription id, etc).
* **category** (string) - Optional: Filter by exact recommendation category. Ignored when type is provided.
* **type** (string) - Optional: Fuzzy filter by recommendation type using a case-insensitive literal substring. Examples: aws, aws:ec2, aws:ec2:rightsizing.
* **provider** (string) - Optional: Filter by provider.
* Allowed values: `aws`, `gcp`, `azure`, `kubernetes`, `datadog`
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/recommendations/get-all-recommendations](https://docs.vantage.sh/api/recommendations/get-all-recommendations)
***
### GET /recommendations/by\_type/{type}/resources
**Get all resources for a recommendation type**
Return all Active Resources associated with recommendations of the specified type.
#### Path Parameters
* **type** (path) (string) - **Required**
#### Query Parameters
* **provider\_ids** (array) - Optional: Filter by one or more providers. Requires workspace\_token.
* **billing\_account\_ids** (array) - Optional: Filter by billing account identifiers. Requires workspace\_token.
* **account\_ids** (array) - Optional: Filter by account identifiers. Requires workspace\_token.
* **regions** (array) - Optional: Filter by region slugs (e.g. us-east-1, eastus, asia-east1). Requires workspace\_token.
* **tag\_key** (string) - Optional: Filter by tag key (must be used with tag\_value). Requires workspace\_token.
* **tag\_value** (string) - Optional: Filter by tag value (requires tag\_key). Requires workspace\_token.
* **start\_date** (string) - Optional: Filter recommendations created on/after this YYYY-MM-DD date. Requires workspace\_token.
* **end\_date** (string) - Optional: Filter recommendations created on/before this YYYY-MM-DD date. Requires workspace\_token.
* **status** (string) - Optional: Filter by status.
* Allowed values: `active`, `archived`
* **min\_savings** (number (float)) - Optional: Filter by recommendations whose potential savings are greater than or equal to this amount, in the workspace's currency. Requires workspace\_token.
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The number of results to return. The maximum is 1000.
* **workspace\_token** (string) - **Required**: The workspace token to filter recommendations by. Required.
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/recommendations/get-all-resources-for-a-recommendation-type](https://docs.vantage.sh/api/recommendations/get-all-resources-for-a-recommendation-type)
***
### GET /recommendations/{recommendation_token}
**Get recommendation by token**
Return a Recommendation.
#### Path Parameters
* **recommendation\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/recommendations/get-recommendation-by-token](https://docs.vantage.sh/api/recommendations/get-recommendation-by-token)
***
### GET /recommendations/{recommendation_token}/resources
**Get all resources for a recommendation**
Return all Active Resources, including Recommendation Actions, referenced in this Recommendation.
#### Path Parameters
* **recommendation\_token** (path) (string) - **Required**
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The number of results to return. Defaults to 25. The maximum is 500.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/recommendations/get-all-resources-for-a-recommendation](https://docs.vantage.sh/api/recommendations/get-all-resources-for-a-recommendation)
***
### GET /recommendations/{recommendation_token}/resources/{resource_token}
**Get specific resource for a recommendation**
Return an Active Resource, including Recommendation Actions, referenced in this Recommendation.
#### Path Parameters
* **recommendation\_token** (path) (string) - **Required**
* **resource\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/recommendations/get-specific-resource-for-a-recommendation](https://docs.vantage.sh/api/recommendations/get-specific-resource-for-a-recommendation)
***
## ReportForecasts
### GET /report\_forecasts
**Get all report forecasts**
Return all scenario-model ReportForecasts for a CostReport.
#### Query Parameters
* **cost\_report\_token** (string) - **Required**
* **page** (integer (int32)) - Optional
* **limit** (integer (int32)) - Optional
#### Responses
**200**: Return all scenario-model ReportForecasts for a CostReport.
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/reportforecasts/get-all-report-forecasts](https://docs.vantage.sh/api/reportforecasts/get-all-report-forecasts)
***
### POST /report\_forecasts
**Create report forecast**
Create a scenario-model ReportForecast.
#### Request Body
```json theme={null}
{
"cost_report_token": string // required,
"title": string // required,
"scenario_model_tokens": [string],
"business_metric_token": string,
"set_as_default": boolean
}
```
#### Responses
**201**: Create a scenario-model ReportForecast.
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/reportforecasts/create-report-forecast](https://docs.vantage.sh/api/reportforecasts/create-report-forecast)
***
### DELETE /report\_forecasts/{report_forecast_token}
**Delete report forecast**
Delete a scenario-model ReportForecast.
#### Path Parameters
* **report\_forecast\_token** (path) (string) - **Required**
#### Responses
**204**: Delete a scenario-model ReportForecast.
**403**: Forbidden
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/reportforecasts/delete-report-forecast](https://docs.vantage.sh/api/reportforecasts/delete-report-forecast)
***
### GET /report\_forecasts/{report_forecast_token}
**Get report forecast by token**
Return a scenario-model ReportForecast.
#### Path Parameters
* **report\_forecast\_token** (path) (string) - **Required**
#### Responses
**200**: Return a scenario-model ReportForecast.
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/reportforecasts/get-report-forecast-by-token](https://docs.vantage.sh/api/reportforecasts/get-report-forecast-by-token)
***
### PUT /report\_forecasts/{report_forecast_token}
**Update report forecast**
Update a scenario-model ReportForecast.
#### Path Parameters
* **report\_forecast\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string,
"scenario_model_tokens": [string],
"business_metric_token": string,
"set_as_default": boolean
}
```
#### Responses
**200**: Update a scenario-model ReportForecast.
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/reportforecasts/update-report-forecast](https://docs.vantage.sh/api/reportforecasts/update-report-forecast)
***
## ReportNotifications
### GET /report\_notifications
**Get all report notifications**
Return all ReportNotifications.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **workspace\_token** (string) - Optional: Filter by workspace token.
* **q** (string) - Optional: Search report notifications by title.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/reportnotifications/get-all-report-notifications](https://docs.vantage.sh/api/reportnotifications/get-all-report-notifications)
***
### POST /report\_notifications
**Create report notification**
Create a ReportNotification.
#### Request Body
```json theme={null}
{
"title": string // required // The title of the ReportNotification,
"cost_report_token": string // required // The CostReport token,
"workspace_token": string // The token of the Workspace to add the ReportNotification to. Required if the API token is associated with multiple Workspaces,
"user_tokens": [string] // The Users that receive the notification,
"recipient_emails": [string] // Email addresses that receive the notification. Must be organization users, on the account's SSO domain, or an approved third-party service address,
"recipient_channels": [string] // The Slack or Microsoft Teams channels that receive the notification,
"frequency": string // required // The frequency the ReportNotification is sent. Possible values: daily, weekly, monthly,
"change": string // required // The type of change the ReportNotification is tracking. Possible values: percentage, dollars
}
```
#### Responses
**201**: Created
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/reportnotifications/create-report-notification](https://docs.vantage.sh/api/reportnotifications/create-report-notification)
***
### DELETE /report\_notifications/{report_notification_token}
**Delete report notification**
Delete a ReportNotification.
#### Path Parameters
* **report\_notification\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/reportnotifications/delete-report-notification](https://docs.vantage.sh/api/reportnotifications/delete-report-notification)
***
### GET /report\_notifications/{report_notification_token}
**Get report notification by token**
Return a ReportNotification.
#### Path Parameters
* **report\_notification\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/reportnotifications/get-report-notification-by-token](https://docs.vantage.sh/api/reportnotifications/get-report-notification-by-token)
***
### PUT /report\_notifications/{report_notification_token}
**Update report notification**
Update a ReportNotification.
#### Path Parameters
* **report\_notification\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the ReportNotification,
"cost_report_token": string // The CostReport token,
"user_tokens": [string] // The Users that receive the notification,
"recipient_emails": [string] // Email addresses that receive the notification. Must be organization users, on the account's SSO domain, or an approved third-party service address,
"recipient_channels": [string] // The Slack or Microsoft Teams channels that receive the notification,
"frequency": string // The frequency the ReportNotification is sent. Possible values: daily, weekly, monthly,
"change": string // The type of change the ReportNotification is tracking. Possible values: percentage, dollars
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/reportnotifications/update-report-notification](https://docs.vantage.sh/api/reportnotifications/update-report-notification)
***
## ResourceReports
### GET /resource\_reports
**Get all resource reports**
Return all ResourceReports.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The number of results to return. The maximum is 1000.
* **workspace\_token** (string) - Optional: Filter by workspace token.
* **q** (string) - Optional: A search query to filter ResourceReports by title.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/resourcereports/get-all-resource-reports](https://docs.vantage.sh/api/resourcereports/get-all-resource-reports)
***
### POST /resource\_reports
**Create resource report**
Create a ResourceReport.
#### Request Body
```json theme={null}
{
"workspace_token": string // required // The token of the Workspace to add the ResourceReport to,
"title": string // The title of the ResourceReport,
"filter": string // The filter query language to apply to the ResourceReport. Additional documentation available at https://docs.vantage.sh/vql,
"columns": [string] // Array of column names to display in the table. Column names should match those returned by the /resource_reports/columns endpoint. The order determines the display order. Only available for reports with a single resource type filter,
"folder_token": string // The token of the Folder to add the ResourceReport to
}
```
#### Responses
**201**: Created
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/resourcereports/create-resource-report](https://docs.vantage.sh/api/resourcereports/create-resource-report)
***
### GET /resource\_reports/columns
**Get resource report columns**
List available columns for a resource type.
#### Query Parameters
* **resource\_type** (string) - **Required**: VQL resource type name ([https://docs.vantage.sh/vql\_resource\_report#costs-by-resource-type](https://docs.vantage.sh/vql_resource_report#costs-by-resource-type))
#### Responses
**200**: Returns array of available column names for the specified resource type
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/resourcereports/get-resource-report-columns](https://docs.vantage.sh/api/resourcereports/get-resource-report-columns)
***
### DELETE /resource\_reports/{resource_report_token}
**Delete resource report**
Delete a ResourceReport.
#### Path Parameters
* **resource\_report\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/resourcereports/delete-resource-report](https://docs.vantage.sh/api/resourcereports/delete-resource-report)
***
### GET /resource\_reports/{resource_report_token}
**Get resource report by token**
Return a ResourceReport.
#### Path Parameters
* **resource\_report\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/resourcereports/get-resource-report-by-token](https://docs.vantage.sh/api/resourcereports/get-resource-report-by-token)
***
### PUT /resource\_reports/{resource_report_token}
**Update resource report**
Update a ResourceReport.
#### Path Parameters
* **resource\_report\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the ResourceReport,
"filter": string // The filter query language to apply to the ResourceReport. Additional documentation available at https://docs.vantage.sh/vql,
"columns": [string] // Array of column names to display in the table. Column names should match those returned by the /resource_reports/columns endpoint. The order determines the display order. Only available for reports with a single resource type filter,
"folder_token": string // The token of the Folder to move the ResourceReport to
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/resourcereports/update-resource-report](https://docs.vantage.sh/api/resourcereports/update-resource-report)
***
## Resources
### GET /resources
**Get resources**
Return Resources contained in a ResourceReport
#### Query Parameters
* **resource\_report\_token** (string) - Optional: The ResourceReport token.
* **filter** (string) - Optional: The filter query language to apply to the Resources. Additional documentation available at [https://docs.vantage.sh/vql](https://docs.vantage.sh/vql).
* **workspace\_token** (string) - Optional: The Workspace in which the Resources are located.
* **include\_cost** (boolean) - Optional: Include cost information in the response.
* **page** (integer (int32)) - Optional: The page number for pagination.
* **limit** (integer (int32)) - Optional: The number of resources to return per page.
#### Responses
**200**: OK
**400**: BadRequest
**402**: PaymentRequired
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/resources/get-resources](https://docs.vantage.sh/api/resources/get-resources)
***
### GET /resources/{resource_token}
**Get resource by token**
Return a single Resource
#### Path Parameters
* **resource\_token** (path) (string) - **Required**
#### Query Parameters
* **include\_cost** (boolean) - Optional: Include cost information in the response.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/resources/get-resource-by-token](https://docs.vantage.sh/api/resources/get-resource-by-token)
***
## SavedFilters
### GET /saved\_filters
**Get all saved filters**
Return all SavedFilters that can be applied to a CostReport.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **q** (string) - Optional: Search saved filters by title.
* **workspace\_token** (string) - Optional: The workspace token of the saved filters to return.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/savedfilters/get-all-saved-filters](https://docs.vantage.sh/api/savedfilters/get-all-saved-filters)
***
### POST /saved\_filters
**Create saved filter**
Create a SavedFilter for CostReports.
#### Request Body
```json theme={null}
{
"title": string // required // The title of the SavedFilter,
"workspace_token": string // The Workspace to associate the SavedFilter with. Required if the API token is associated with multiple Workspaces,
"filter": string // The filter query language to apply to the SavedFilter, which subsequently gets applied to a CostReport. Additional documentation available at https://docs.vantage.sh/vql
}
```
#### Responses
**201**: Created
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/savedfilters/create-saved-filter](https://docs.vantage.sh/api/savedfilters/create-saved-filter)
***
### DELETE /saved\_filters/{saved_filter_token}
**Delete saved filter**
Delete a SavedFilter for CostReports.
#### Path Parameters
* **saved\_filter\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/savedfilters/delete-saved-filter](https://docs.vantage.sh/api/savedfilters/delete-saved-filter)
***
### GET /saved\_filters/{saved_filter_token}
**Get saved filter by token**
Return a specific SavedFilter.
#### Path Parameters
* **saved\_filter\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/savedfilters/get-saved-filter-by-token](https://docs.vantage.sh/api/savedfilters/get-saved-filter-by-token)
***
### PUT /saved\_filters/{saved_filter_token}
**Update saved filter**
Update a SavedFilter for CostReports.
#### Path Parameters
* **saved\_filter\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the SavedFilter,
"filter": string // The filter query language to apply to the SavedFilter, which subsequently gets applied to a CostReport. Additional documentation available at https://docs.vantage.sh/vql
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/savedfilters/update-saved-filter](https://docs.vantage.sh/api/savedfilters/update-saved-filter)
***
## ScenarioModels
### GET /scenario\_models
**Get all scenario models**
Return all ScenarioModels.
#### Query Parameters
* **page** (integer (int32)) - Optional
* **limit** (integer (int32)) - Optional
#### Responses
**200**: Return all ScenarioModels.
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/scenariomodels/get-all-scenario-models](https://docs.vantage.sh/api/scenariomodels/get-all-scenario-models)
***
### POST /scenario\_models
**Create scenario model**
Create a ScenarioModel.
#### Request Body
```json theme={null}
{
"title": string // required,
"priority": integer,
"provider": string,
"service": string,
"workspace_token": string,
"periods": [ // The periods for the ScenarioModel
{
"start_at": string // required,
"end_at": string,
"amount": number // required,
"amount_type": string // required // Allowed values: `dollar`, `percent`
}
]
}
```
#### Responses
**201**: Create a ScenarioModel.
**403**: Forbidden
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/scenariomodels/create-scenario-model](https://docs.vantage.sh/api/scenariomodels/create-scenario-model)
***
### DELETE /scenario\_models/{scenario_model_token}
**Delete scenario model**
Delete a ScenarioModel.
#### Path Parameters
* **scenario\_model\_token** (path) (string) - **Required**
#### Responses
**204**: Delete a ScenarioModel.
**403**: Forbidden
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/scenariomodels/delete-scenario-model](https://docs.vantage.sh/api/scenariomodels/delete-scenario-model)
***
### GET /scenario\_models/{scenario_model_token}
**Get scenario model by token**
Return a ScenarioModel.
#### Path Parameters
* **scenario\_model\_token** (path) (string) - **Required**
#### Responses
**200**: Return a ScenarioModel.
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/scenariomodels/get-scenario-model-by-token](https://docs.vantage.sh/api/scenariomodels/get-scenario-model-by-token)
***
### PUT /scenario\_models/{scenario_model_token}
**Update scenario model**
Update a ScenarioModel.
#### Path Parameters
* **scenario\_model\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string,
"priority": integer,
"provider": string,
"service": string,
"workspace_token": string,
"periods": [ // The periods for the ScenarioModel
{
"start_at": string // required,
"end_at": string,
"amount": number // required,
"amount_type": string // required // Allowed values: `dollar`, `percent`
}
]
}
```
#### Responses
**200**: Update a ScenarioModel.
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/scenariomodels/update-scenario-model](https://docs.vantage.sh/api/scenariomodels/update-scenario-model)
***
## Segments
### GET /segments
**Get all segments**
Return all Segments.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **q** (string) - Optional: Search segments by title.
* **workspace\_token** (string) - Optional: The workspace token of the segments to return.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/segments/get-all-segments](https://docs.vantage.sh/api/segments/get-all-segments)
***
### POST /segments
**Create segment**
Create a Segment.
#### Request Body
```json theme={null}
{
"title": string // required // The title of the Segment,
"description": string // The description of the Segment,
"priority": integer // The priority of the Segment,
"track_unallocated": boolean // Track Unallocated Costs which are not assigned to any of the created Segments,
"report_settings": { // Report settings configurable on top-level Segments
"include_credits": boolean // Reports created under this Segment will include credits,
"include_refunds": boolean // Reports created under this Segment will include refunds,
"include_discounts": boolean // Reports created under this Segment will include discounts,
"include_tax": boolean // Reports created under this Segment will include tax,
"amortize": boolean // Reports created under this Segment will amortize
},
"workspace_token": string // The token of the Workspace to add the Segment to. Ignored if 'segment_token' is set. Required if the API token is associated with multiple Workspaces,
"filter": string // The filter query language to apply to the Segment. Additional documentation available at https://docs.vantage.sh/vql,
"parent_segment_token": string // The token of the parent Segment this new Segment belongs to. Determines the Workspace the segment is assigned to
}
```
#### Responses
**201**: Created
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/segments/create-segment](https://docs.vantage.sh/api/segments/create-segment)
***
### DELETE /segments/{segment_token}
**Delete segment**
Delete a Segment.
#### Path Parameters
* **segment\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/segments/delete-segment](https://docs.vantage.sh/api/segments/delete-segment)
***
### GET /segments/{segment_token}
**Get segment by token**
Return a Segment.
#### Path Parameters
* **segment\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/segments/get-segment-by-token](https://docs.vantage.sh/api/segments/get-segment-by-token)
***
### PUT /segments/{segment_token}
**Update segment**
Update a Segment.
#### Path Parameters
* **segment\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"title": string // The title of the Segment,
"description": string // The description of the Segment,
"priority": integer // The priority of the Segment,
"track_unallocated": boolean // Track Unallocated Costs which are not assigned to any of the created Segments,
"report_settings": { // Report settings configurable on top-level Segments
"include_credits": boolean // Reports created under this Segment will include credits,
"include_refunds": boolean // Reports created under this Segment will include refunds,
"include_discounts": boolean // Reports created under this Segment will include discounts,
"include_tax": boolean // Reports created under this Segment will include tax,
"amortize": boolean // Reports created under this Segment will amortize
},
"filter": string // The filter query language to apply to the Segment. Additional documentation available at https://docs.vantage.sh/vql,
"parent_segment_token": string // The token of the parent Segment this new Segment belongs to. Determines the Workspace the segment is assigned to
}
```
#### Responses
**200**: OK
**400**: BadRequest
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/segments/update-segment](https://docs.vantage.sh/api/segments/update-segment)
***
## Tags
### GET /tags
**Get all tags**
Return all Tags that the current API token has access to.
#### Query Parameters
* **providers** (array) - Optional: An array of providers to scope Tags by.
* **search\_query** (string) - Optional: A search query to filter Tags by tag key.
* **sort\_direction** (string) - Optional: The direction in which you would like to sort the data by. Defaults to 'asc'.
* Allowed values: `asc`, `desc`
* **page** (integer (int32)) - Optional: The page of results to return.
* Default: `1`
* **limit** (integer (int32)) - Optional: The number of results to return per page. Defaults to 100. The maximum is 1000.
* Default: `100`
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/tags/get-all-tags](https://docs.vantage.sh/api/tags/get-all-tags)
***
### PUT /tags
**Update tag**
Updates an existing Tag.
#### Request Body
```json theme={null}
{
"tag_key": string,
"tag_keys": [string],
"hidden": boolean // Whether the Tag is hidden from the Vantage UI,
"preferred": boolean // Whether the Tag is marked as preferred in the Vantage UI
}
```
#### Responses
**200**: OK
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/tags/update-tag](https://docs.vantage.sh/api/tags/update-tag)
***
### GET /tags/{key}/values
**Get tag values**
Returns corresponding TagValues for a given Tag.
#### Path Parameters
* **key** (path) (string) - **Required**: The key of the Tag for which you would like to retrieve TagValues.
#### Query Parameters
* **providers** (array) - Optional: An array of providers to scope TagValues by.
* **sort\_direction** (string) - Optional: The direction in which to sort the TagValues. Defaults to 'asc'.
* Allowed values: `asc`, `desc`
* Default: `asc`
* **search\_query** (string) - Optional: A search query to filter TagValues by the value name.
* **page** (integer (int32)) - Optional: The page of results to return.
* Default: `1`
* **limit** (integer (int32)) - Optional: The number of results to return per page. Defaults to 100. The maximum is 1000.
* Default: `100`
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/tags/get-tag-values](https://docs.vantage.sh/api/tags/get-tag-values)
***
## Teams
### GET /teams
**Get all teams**
Return all Teams that the current API token has access to.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **q** (string) - Optional: Search teams by name.
* **workspace\_token** (string) - Optional: Filter by workspace token.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/teams/get-all-teams](https://docs.vantage.sh/api/teams/get-all-teams)
***
### POST /teams
**Create team**
Create a new Team.
#### Request Body
```json theme={null}
{
"name": string // required // The name of the Team,
"description": string // The description of the Team,
"workspace_tokens": [string] // The Workspace tokens to associate to the Team,
"user_tokens": [string] // The User tokens to associate to the Team,
"user_emails": [string] // The User emails to associate to the Team,
"role": string // The role to assign to the provided Users. Defaults to 'editor' which has editor permissions. Allowed values: `owner`, `editor`, `viewer`,
"default_dashboard_token": string // The token of a Dashboard to set as the Team default. Send null to clear
}
```
#### Responses
**201**: Created
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/teams/create-team](https://docs.vantage.sh/api/teams/create-team)
***
### DELETE /teams/{team_token}
**Delete team**
Delete a Team.
#### Path Parameters
* **team\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/teams/delete-team](https://docs.vantage.sh/api/teams/delete-team)
***
### GET /teams/{team_token}
**Get team by token**
Return a specific Team.
#### Path Parameters
* **team\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/teams/get-team-by-token](https://docs.vantage.sh/api/teams/get-team-by-token)
***
### PUT /teams/{team_token}
**Update team**
Update a Team.
#### Path Parameters
* **team\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"name": string // The name of the Team,
"description": string // The description of the Team,
"workspace_tokens": [string] // The Workspace tokens to associate to the Team,
"user_tokens": [string] // The User tokens to associate to the Team,
"user_emails": [string] // The User emails to associate to the Team,
"role": string // The role to assign to the provided Users. Defaults to 'editor' which has editor permissions. Allowed values: `owner`, `editor`, `viewer`,
"default_dashboard_token": string // The token of a Dashboard to set as the Team default. Send null to clear
}
```
#### Responses
**200**: OK
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/teams/update-team](https://docs.vantage.sh/api/teams/update-team)
***
### GET /teams/{team_token}/members
**Get team members**
Return all members of a Team.
#### Path Parameters
* **team\_token** (path) (string) - **Required**
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/teams/get-team-members](https://docs.vantage.sh/api/teams/get-team-members)
***
### POST /teams/{team_token}/members
**Add team member**
Add a member to a Team.
#### Path Parameters
* **team\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"user_email": string // required // The email address of the user to add to the Team,
"role": string // required // The role to assign to the user. Defaults to 'editor'. Allowed values: `owner`, `editor`, `viewer`, `integration_owner`
}
```
#### Responses
**201**: Created
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/teams/add-team-member](https://docs.vantage.sh/api/teams/add-team-member)
***
### DELETE /teams/{team_token}/members/{user_token}
**Remove team member**
Remove a member from a Team.
#### Path Parameters
* **team\_token** (path) (string) - **Required**
* **user\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/teams/remove-team-member](https://docs.vantage.sh/api/teams/remove-team-member)
***
## UnitCosts
### GET /unit\_costs
**Get all unit costs for a cost report**
Return all UnitCosts for a CostReport.
#### Query Parameters
* **cost\_report\_token** (string) - **Required**: The CostReport token.
* **start\_date** (string) - Optional: First date you would like to filter unit costs from. Defaults to the report's default. ISO 8601 formatted.
* **end\_date** (string) - Optional: Last date you would like to filter unit costs to. Defaults to the report's default. ISO 8601 formatted.
* **date\_bin** (string) - Optional: The date bin of the unit costs. Defaults to the report's default or day.
* Allowed values: `day`, `week`, `month`, `quarter`, `hour`
* **order** (string) - Optional: Whether to order unit costs by date in an ascending or descending manner.
* Allowed values: `asc`, `desc`
* Default: `desc`
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **page** (integer (int32)) - Optional: The page of results to return.
#### Responses
**200**: OK
**400**: BadRequest
**402**: PaymentRequired
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/unitcosts/get-all-unit-costs-for-a-cost-report](https://docs.vantage.sh/api/unitcosts/get-all-unit-costs-for-a-cost-report)
***
### POST /unit\_costs/data\_exports
**Generate data export of unit costs**
Generate a DataExport of unit costs.
#### Request Body
```json theme={null}
{
"cost_report_token": string // required // The CostReport token,
"workspace_token": string // The token of the Workspace to query costs from. Required if the API token is associated with multiple Workspaces,
"start_date": string // First date you would like to filter unit costs from. Defaults to the report's default. ISO 8601 formatted,
"end_date": string // Last date you would like to filter unit costs to. Defaults to the report's default. ISO 8601 formatted,
"date_bin": string // The date bin of the unit costs. Defaults to the report's default or day. Allowed values: `day`, `week`, `month`, `quarter`, `hour`
}
```
#### Responses
**202**: The data export has been queued and will be available at the location specified in the Location header.
**400**: BadRequest
**402**: PaymentRequired
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/unitcosts/generate-data-export-of-unit-costs](https://docs.vantage.sh/api/unitcosts/generate-data-export-of-unit-costs)
***
## UserFeedback
### POST /user\_feedback
**Submit user feedback**
Provide UserFeedback for our product and features.
#### Request Body
```json theme={null}
{
"message": string // required // UserFeedback message
}
```
#### Responses
**201**: Provide UserFeedback for our product and features.
**400**: BadRequest
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/userfeedback/submit-user-feedback](https://docs.vantage.sh/api/userfeedback/submit-user-feedback)
***
## Users
### GET /users
**Get all users**
Return all Users that the current API token has access to.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
#### Responses
**200**: OK
**403**: Forbidden
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/users/get-all-users](https://docs.vantage.sh/api/users/get-all-users)
***
### GET /users/{user_token}
**Get user by token**
Return a specific User.
#### Path Parameters
* **user\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/users/get-user-by-token](https://docs.vantage.sh/api/users/get-user-by-token)
***
### PUT /users/{user_token}
**Update a user**
Update a specific User.
#### Path Parameters
* **user\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"default_dashboard_token": string // The token of a Dashboard to set as the User default. Send null to clear
}
```
#### Responses
**200**: OK
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/users/update-a-user](https://docs.vantage.sh/api/users/update-a-user)
***
## VirtualTags
### GET /virtual\_tag\_configs
**Get all virtual tag configs**
Return all VirtualTagConfigs that the current API token has access to.
#### Query Parameters
* **q** (string) - Optional: A search query to filter VirtualTagConfigs by key.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/virtualtags/get-all-virtual-tag-configs](https://docs.vantage.sh/api/virtualtags/get-all-virtual-tag-configs)
***
### POST /virtual\_tag\_configs
**Create virtual tag config**
Create a new VirtualTagConfig.
#### Request Body
```json theme={null}
{
"key": string // required // The key of the VirtualTagConfig,
"overridable": boolean // required // Whether the VirtualTagConfig can override a provider-supplied tag on a matching Cost,
"backfill_until": string // The earliest month the VirtualTagConfig should be backfilled to,
"collapsed_tag_keys": [ // Tag keys to collapse values for
{
"key": string // required // The tag key to collapse values for,
"providers": [string] // Provider-only scope for this collapsed tag key. Invalid when filter is set; include provider restrictions in filter instead. Defaults to all providers,
"filter": string // The VQL filter this collapsed tag key applies to. When set, do not also set providers; include any provider restrictions directly in filter
}
],
"values": [ // Values for the VirtualTagConfig, with match precedence determined by order in the list
{
"filter": string // required // The filter query language to apply to the value. Additional documentation available at https://docs.vantage.sh/vql,
"name": string // The name of the value,
"business_metric_token": string // The token of an associated business metric,
"label_key": string // The business metric label key used for this virtual tag value,
"label_values": [string] // Optional business metric label values. An empty array includes every value for the label key,
"label_filters": object // ClickHouse BusinessMetric row filters. Each key must match, and values within a key are alternatives. Cannot include the fan-out label_key. Send null or an empty object to clear,
"display_name": string // The display name for an allocation value (cost_metric or percentages). Invalid when name is set,
"label_transforms": [
{
"type": string // required,
"delimiter": string,
"index": integer,
"template": string
}
],
"cost_metric": {
"filter": string // required,
"aggregation": { // required
"tag": string // required
}
},
"percentages": [
{
"value": string // required,
"pct": number // required
}
],
"date_ranges": [ // Date ranges restricting when this value applies. Each range has optional start_date and end_date (inclusive, YYYY-MM-DD)
{
"start_date": string // Inclusive start date (YYYY-MM-DD), or null for unbounded,
"end_date": string // Inclusive end date (YYYY-MM-DD), or null for unbounded
}
]
}
]
}
```
#### Responses
**201**: Created
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/virtualtags/create-virtual-tag-config](https://docs.vantage.sh/api/virtualtags/create-virtual-tag-config)
***
### GET /virtual\_tag\_configs/async/{request_id}
**Get async virtual tag config update status**
Check the status of an async VirtualTagConfig update.
#### Path Parameters
* **request\_id** (path) (string) - **Required**
#### Responses
**200**: Request completed successfully
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/virtualtags/get-async-virtual-tag-config-update-status](https://docs.vantage.sh/api/virtualtags/get-async-virtual-tag-config-update-status)
***
### DELETE /virtual\_tag\_configs/{token}
**Delete virtual tag config**
Deletes an existing VirtualTagConfig.
#### Path Parameters
* **token** (path) (string) - **Required**
#### Responses
**204**: No Content
**403**: Forbidden
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/virtualtags/delete-virtual-tag-config](https://docs.vantage.sh/api/virtualtags/delete-virtual-tag-config)
***
### GET /virtual\_tag\_configs/{token}
**Get virtual tag config by token**
Return a specific VirtualTagConfig.
#### Path Parameters
* **token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/virtualtags/get-virtual-tag-config-by-token](https://docs.vantage.sh/api/virtualtags/get-virtual-tag-config-by-token)
***
### PUT /virtual\_tag\_configs/{token}
**Update virtual tag config**
Updates an existing VirtualTagConfig.
#### Path Parameters
* **token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"key": string // The key of the VirtualTagConfig,
"overridable": boolean // Whether the VirtualTagConfig can override a provider-supplied tag on a matching Cost,
"backfill_until": string // The earliest month the VirtualTagConfig should be backfilled to,
"collapsed_tag_keys": [ // Tag keys to collapse values for
{
"key": string // required // The tag key to collapse values for,
"providers": [string] // Provider-only scope for this collapsed tag key. Invalid when filter is set; include provider restrictions in filter instead. Defaults to all providers,
"filter": string // The VQL filter this collapsed tag key applies to. When set, do not also set providers; include any provider restrictions directly in filter
}
],
"values": [ // Values for the VirtualTagConfig, with match precedence determined by order in the list
{
"filter": string // required // The filter query language to apply to the value. Additional documentation available at https://docs.vantage.sh/vql,
"name": string // The name of the value,
"business_metric_token": string // The token of an associated business metric,
"label_key": string // The business metric label key used for this virtual tag value,
"label_values": [string] // Optional business metric label values. An empty array includes every value for the label key,
"label_filters": object // ClickHouse BusinessMetric row filters. Each key must match, and values within a key are alternatives. Cannot include the fan-out label_key. Send null or an empty object to clear,
"display_name": string // The display name for an allocation value (cost_metric or percentages). Invalid when name is set,
"label_transforms": [
{
"type": string // required,
"delimiter": string,
"index": integer,
"template": string
}
],
"cost_metric": {
"filter": string // required,
"aggregation": { // required
"tag": string // required
}
},
"percentages": [
{
"value": string // required,
"pct": number // required
}
],
"date_ranges": [ // Date ranges restricting when this value applies. Each range has optional start_date and end_date (inclusive, YYYY-MM-DD)
{
"start_date": string // Inclusive start date (YYYY-MM-DD), or null for unbounded,
"end_date": string // Inclusive end date (YYYY-MM-DD), or null for unbounded
}
]
}
]
}
```
#### Responses
**200**: OK
**202**: Request accepted for processing
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/virtualtags/update-virtual-tag-config](https://docs.vantage.sh/api/virtualtags/update-virtual-tag-config)
***
### PUT /virtual\_tag\_configs/{token}/async
**Update virtual tag config asynchronously**
Asynchronously updates an existing VirtualTagConfig.
#### Path Parameters
* **token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"key": string // The key of the VirtualTagConfig,
"overridable": boolean // Whether the VirtualTagConfig can override a provider-supplied tag on a matching Cost,
"backfill_until": string // The earliest month the VirtualTagConfig should be backfilled to,
"collapsed_tag_keys": [ // Tag keys to collapse values for
{
"key": string // required // The tag key to collapse values for,
"providers": [string] // Provider-only scope for this collapsed tag key. Invalid when filter is set; include provider restrictions in filter instead. Defaults to all providers,
"filter": string // The VQL filter this collapsed tag key applies to. When set, do not also set providers; include any provider restrictions directly in filter
}
],
"values": [ // Values for the VirtualTagConfig, with match precedence determined by order in the list
{
"filter": string // required // The filter query language to apply to the value. Additional documentation available at https://docs.vantage.sh/vql,
"name": string // The name of the value,
"business_metric_token": string // The token of an associated business metric,
"label_key": string // The business metric label key used for this virtual tag value,
"label_values": [string] // Optional business metric label values. An empty array includes every value for the label key,
"label_filters": object // ClickHouse BusinessMetric row filters. Each key must match, and values within a key are alternatives. Cannot include the fan-out label_key. Send null or an empty object to clear,
"display_name": string // The display name for an allocation value (cost_metric or percentages). Invalid when name is set,
"label_transforms": [
{
"type": string // required,
"delimiter": string,
"index": integer,
"template": string
}
],
"cost_metric": {
"filter": string // required,
"aggregation": { // required
"tag": string // required
}
},
"percentages": [
{
"value": string // required,
"pct": number // required
}
],
"date_ranges": [ // Date ranges restricting when this value applies. Each range has optional start_date and end_date (inclusive, YYYY-MM-DD)
{
"start_date": string // Inclusive start date (YYYY-MM-DD), or null for unbounded,
"end_date": string // Inclusive end date (YYYY-MM-DD), or null for unbounded
}
]
}
]
}
```
#### Responses
**202**: Request accepted for processing
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/virtualtags/update-virtual-tag-config-asynchronously](https://docs.vantage.sh/api/virtualtags/update-virtual-tag-config-asynchronously)
***
### GET /virtual\_tag\_configs/{token}/status
**Get virtual tag config processing status**
Return the processing status of a specific VirtualTagConfig.
#### Path Parameters
* **token** (path) (string) - **Required**
#### Responses
**200**: Processing is complete
**202**: Processing is still in progress
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/virtualtags/get-virtual-tag-config-processing-status](https://docs.vantage.sh/api/virtualtags/get-virtual-tag-config-processing-status)
***
### POST /virtual\_tag\_configs/{virtual_tag_config_token}/values
**Create virtual tag config value**
Create a VirtualTagConfigValue.
#### Path Parameters
* **virtual\_tag\_config\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"filter": string // required // The filter query language to apply to the value. Additional documentation available at https://docs.vantage.sh/vql,
"name": string // The name of the value,
"business_metric_token": string // The token of an associated business metric,
"label_key": string // The business metric label key used for this virtual tag value,
"label_values": [string] // Business metric label values. An empty array includes every value for the label key,
"label_filters": { // ClickHouse BusinessMetric row filters. Each key must match, and values within a key are alternatives. Cannot include the fan-out label_key. Null and an empty object leave stored filters unchanged
},
"display_name": string // The display name for a cost metric or percentage allocation value,
"label_transforms": [
{
"type": string // required // Allowed values: `split`, `format`,
"delimiter": string,
"index": integer,
"template": string
}
],
"cost_metric": {
"filter": string // required,
"aggregation": { // required
"tag": string // required
}
},
"percentages": [
{
"value": string // required,
"pct": number // required
}
],
"date_ranges": [ // Date ranges restricting when this value applies
{
"start_date": string,
"end_date": string
}
]
}
```
#### Responses
**201**: Created
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/virtualtags/create-virtual-tag-config-value](https://docs.vantage.sh/api/virtualtags/create-virtual-tag-config-value)
***
### DELETE /virtual\_tag\_configs/{virtual_tag_config_token}/values/{virtual_tag_config_value_token}
**Delete virtual tag config value**
Delete a VirtualTagConfigValue.
#### Path Parameters
* **virtual\_tag\_config\_token** (path) (string) - **Required**
* **virtual\_tag\_config\_value\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**403**: Forbidden
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/virtualtags/delete-virtual-tag-config-value](https://docs.vantage.sh/api/virtualtags/delete-virtual-tag-config-value)
***
### GET /virtual\_tag\_configs/{virtual_tag_config_token}/values/{virtual_tag_config_value_token}
**Get virtual tag config value by token**
Return a VirtualTagConfigValue.
#### Path Parameters
* **virtual\_tag\_config\_token** (path) (string) - **Required**
* **virtual\_tag\_config\_value\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**403**: Forbidden
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/virtualtags/get-virtual-tag-config-value-by-token](https://docs.vantage.sh/api/virtualtags/get-virtual-tag-config-value-by-token)
***
### PATCH /virtual\_tag\_configs/{virtual_tag_config_token}/values/{virtual_tag_config_value_token}
**Update virtual tag config value**
Update a VirtualTagConfigValue.
#### Path Parameters
* **virtual\_tag\_config\_token** (path) (string) - **Required**
* **virtual\_tag\_config\_value\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"filter": string // The filter query language to apply to the value. Additional documentation available at https://docs.vantage.sh/vql,
"name": string // The name of the value,
"business_metric_token": string // The token of an associated business metric,
"label_key": string // The business metric label key used for this virtual tag value,
"label_values": [string] // Business metric label values. An empty array includes every value for the label key,
"label_filters": { // ClickHouse BusinessMetric row filters. Each key must match, and values within a key are alternatives. Cannot include the fan-out label_key. Null and an empty object leave stored filters unchanged
},
"display_name": string // The display name for a cost metric or percentage allocation value,
"label_transforms": [
{
"type": string // required // Allowed values: `split`, `format`,
"delimiter": string,
"index": integer,
"template": string
}
],
"cost_metric": {
"filter": string // required,
"aggregation": { // required
"tag": string // required
}
},
"percentages": [
{
"value": string // required,
"pct": number // required
}
],
"date_ranges": [ // Date ranges restricting when this value applies
{
"start_date": string,
"end_date": string
}
]
}
```
#### Responses
**200**: OK
**400**: BadRequest
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/virtualtags/update-virtual-tag-config-value](https://docs.vantage.sh/api/virtualtags/update-virtual-tag-config-value)
***
## Workspaces
### GET /workspaces
**Get all workspaces**
Return all Workspaces that the current API token has access to.
#### Query Parameters
* **page** (integer (int32)) - Optional: The page of results to return.
* **limit** (integer (int32)) - Optional: The amount of results to return. The maximum is 1000.
* **q** (string) - Optional: Search workspaces by name.
#### Responses
**200**: OK
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/workspaces/get-all-workspaces](https://docs.vantage.sh/api/workspaces/get-all-workspaces)
***
### POST /workspaces
**Create workspace**
Create a workspace
#### Request Body
```json theme={null}
{
"name": string // required // Name of the workspace,
"enable_currency_conversion": boolean // Enable currency conversion for the workspace,
"currency": string // Currency code for the workspace,
"exchange_rate_date": string // The date to use for currency conversion. Allowed values: `daily_rate`, `end_of_billing_period_rate`
}
```
#### Responses
**201**: Created
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/workspaces/create-workspace](https://docs.vantage.sh/api/workspaces/create-workspace)
***
### DELETE /workspaces/{workspace_token}
**Delete workspace**
Delete a workspace
#### Path Parameters
* **workspace\_token** (path) (string) - **Required**
#### Responses
**204**: No Content
**403**: Forbidden
**404**: NotFound
**422**: UnprocessableEntity
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/workspaces/delete-workspace](https://docs.vantage.sh/api/workspaces/delete-workspace)
***
### GET /workspaces/{workspace_token}
**Get workspace by token**
Return a specific Workspace.
#### Path Parameters
* **workspace\_token** (path) (string) - **Required**
#### Responses
**200**: OK
**404**: NotFound
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/workspaces/get-workspace-by-token](https://docs.vantage.sh/api/workspaces/get-workspace-by-token)
***
### PUT /workspaces/{workspace_token}
**Update workspace**
Update a workspace
#### Path Parameters
* **workspace\_token** (path) (string) - **Required**
#### Request Body
```json theme={null}
{
"name": string // Name of the workspace,
"enable_currency_conversion": boolean // Enable currency conversion for the workspace,
"currency": string // Currency code for the workspace. Allowed values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BRL`, `BSD`, `BTC`, `BTN`, `BWP`, `BYN`, `BYR`, `BZD`, `CAD`, `CDF`, `CHF`, `CLF`, `CLP`, `CNY`, `COP`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GGP`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `IMP`, `INR`, `IQD`, `IRR`, `ISK`, `JEP`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LTL`, `LVL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRO`, `MUR`, `MVR`, `MWK`, `MXN`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SSP`, `STD`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `UYU`, `UZS`, `VEF`, `VND`, `VUV`, `WST`, `XAF`, `XCD`, `XDR`, `XOF`, `XPF`, `YER`, `ZAR`, `ZMW`, `ZWL`,
"exchange_rate_date": string // The date to use for currency conversion. Allowed values: `daily_rate`, `end_of_billing_period_rate`
}
```
#### Responses
**200**: OK
**400**: BadRequest
For interactive testing, request/response examples, and detailed schemas, visit: [https://docs.vantage.sh/api/workspaces/update-workspace](https://docs.vantage.sh/api/workspaces/update-workspace)
***
## Summary
This reference includes **233** endpoints across **52** categories.
For the most up-to-date information, always refer to the [OpenAPI specification](https://api.vantage.sh/v2/oas_v3.json) or the individual endpoint pages.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.