Data API

note

Data API is in Open Preview and is not General Availability (GA) at this time. More information about release phases may be found here.

Data API Documentation

The Data API documentation can be found at https://data.api.vegacloud.io/docs.

Purpose

The Vega Platform Data API exists to provide clients with a programmatic way to access report data which is stored in the Vega Platform. This data can be used to build custom reports, dashboards, or to audit findings surfaced in our Platform.

We present the following data to our clients:

• Anomalies Detected
• Resource Costs
• Reservation Utilization
• Tagging Data

Connecting to the Data API

To ensure secure access to the API, we utilize JWT (JSON Web Token) authentication. The token is validated to verify the user's identity and permissions and must be included in the Authorization header of the HTTP request to access protected endpoints.

tip

Generate an API Client Registration to securely access the Data API.

Authentication

The API supports two authentication methods:

1. JWT Authentication (VegaJWTAuth)
2. API Key Authentication (VegaKeyAuth)

All requests must include the appropriate authentication headers.

Common Request Parameters

Most GET endpoints support the following common parameters:

Parameter	Type	Description	Example
page	Integer	The page number to retrieve (starts at 1)	page=1
size	Integer	Number of items per page	size=10
sort_by	String	Comma-delimited sort parameters	sort_by=name:asc,age:desc
filter_by	String	Comma-delimited filter parameters	filter_by=status:=:active,age:>:21

Data Models

The API provides access to the following main data models:

1. Anomalies – Cost usage anomaly data
2. Costs – Cloud resource cost data
3. Discovered Resources – Detected cloud resources across providers
4. Recommendations – Cost optimization recommendations
5. Reserved Instances – Reserved instance details
6. Tags – Resource tagging information

You can retrieve schema information about these models using the /query/schema endpoint.

API Endpoints

Cost Data

Endpoint	Method	Description
/costs	GET	Get cost data across all resources
/costs/spend-daily-by-account	GET	Get daily spend by cloud account
/costs/spend-daily-by-product	GET	Get daily spend by cloud product
/costs/total-spend-monthly-by-account	GET	Get monthly spend by cloud account
/costs/total-spend-monthly-by-product	GET	Get monthly spend by cloud product

Anomalies

Endpoint	Method	Description
/anomalies	GET	Get cost usage anomaly data

Resources

Endpoint	Method	Description
/discovered-resources	GET	Get detected cloud resources
/tags	GET	Get resource tagging information

Recommendations

Endpoint	Method	Description
/recommendations	GET	Get all cost optimization recommendations
/recommendation-aging-snapshots	GET	Get recommendations for aging snapshots
/recommendation-disk-optimization	GET	Get recommendations for disk optimization
/recommendation-family-refresh	GET	Get recommendations for instance family refreshes
/recommendation-idle-databases	GET	Get recommendations for idle databases
/reserved-instances	GET	Get reserved instance information

Query

Endpoint	Method	Description
/query	POST	Execute SQL queries against data models
/query/schema	GET	Get information about available data models and fields

Filtering Data

You can filter data using the filter_by parameter with the following format:

field:operator:value

Multiple filters can be combined with commas and will be joined with AND logic. For example:

filter_by=cloud_provider:=:AWS,product:LIKE:%EC2%,usage_day:between:20230101-20230131

Filter Limitations

Important: For all endpoints except the /query endpoint, multiple filter conditions in the filter_by parameter are always combined using logical AND operations. This means all conditions must be true for a record to be included in the results.

Complex filtering with OR conditions, nested logic, or parenthetical groupings is not supported through the filter_by parameter. For example, you cannot construct a filter like "show resources that are either in AWS OR have costs greater than $100."

For more complex query requirements, use the /query endpoint with a SQL query that can express more sophisticated logic.

Valid Operators

The API supports the following filter operators:

Operator	Description	Example
=	Equal to	status:=:active
<>	Not equal to	status:<>:inactive
>	Greater than	cost:>:100
<	Less than	cost:<:50
>=	Greater than or equal to	cost:>=:100
<=	Less than or equal to	cost:<=:50
BETWEEN or between	Between two values (inclusive)	date:between:20230101-20230131
LIKE or like	Pattern matching (case-sensitive)	name:LIKE:%Server%
ILIKE or ilike	Pattern matching (case-insensitive)	name:ILIKE:%server%
SIMILAR TO or similar to	SQL standard regex pattern matching	name:SIMILAR TO:(server|instance)%
IN or in	Value in a list	status:IN:(active,pending)
NOT IN or not in	Value not in a list	status:NOT IN:(deleted,archived)
IS or is	Equals (usually for NULL values)	owner:IS:NULL
IS NOT or is not	Not equals (usually for NULL values)	owner:IS NOT:NULL
AND or and	Logical AND	status:=:active AND cost:>:100
OR or or	Logical OR	status:=:active OR status:=:pending
NOT or not	Logical NOT	NOT status:=:deleted

Date Range Filters

For date ranges, use the between operator with dates in YYYYMMDD format separated by a hyphen:

usage_day:between:20230101-20230131

Sorting Data

You can sort data using the sort_by parameter with the following format:

field:order

Multiple sort parameters can be combined with commas. For example:

sort_by=cloud_provider:asc,cost:desc

Where:

• field is the field name to sort by
• order is either asc (ascending) or desc (descending)

Filter Field Reference

Types

The following table describes all data types used across the API endpoints with examples of valid values:

Type	Description	Example Values
UUID	Universally Unique Identifier	"123e4567-e89b-12d3-a456-426614174000"
String	Text value	"aws", "us-east-1", "t2.micro", "prod-server-01"
Float64	64-bit floating-point number	123.45, 0.0, -789.12, 1.23e6
Int32	32-bit integer	42, 0, -17, 1000
Int64	64-bit integer	1234567890, 0, -42, 9876543210
DateTime	Date and time value	"2024-01-15T14:30:00Z", "2023-12-31T23:59:59Z"
Boolean	True/false value	true, false

Common Fields

These fields appear across multiple endpoints with consistent types:

Field Name	Type	Description
application	String	Application name or identifier
billing_account_id	String	Billing account identifier
business_group	String	Business group name
business_unit	String	Business unit name
business_unit_id	UUID	Unique identifier for business unit
client_name	String	Client name
cloud_provider	String	Cloud service provider name
cloud_provider_identifier	String	Cloud provider's unique identifier
data_date	DateTime	Date of the data record
environment	String	Environment identifier
exclude_account	String	Account exclusion flag
executive_group	String	Executive group identifier
financial_owner_email	String	Email of financial owner
financial_owner_name	String	Name of financial owner
linked_account_id	String	Linked account identifier
linked_account_name	String	Linked account name
organization_id	UUID	Organization identifier
product_group	String	Product group identifier
resource_id	String	Resource identifier
resource_name	String	Resource name
team	String	Team identifier
technical_owner_email	String	Email of technical owner
technical_owner_name	String	Name of technical owner

Endpoint-Specific Fields

Anomalies (/anomalies)

Field Name	Type
anomaly_hash	String
base_anomaly_flag	String
base_threshold	Float64
base_threshold_cost	Int32
cloud_region	String
cloud_specific_location	String
cloud_zone	String
current_net_fiscal_amount	Float64
current_ondemand_cost	Float64
current_usage_amount	Float64
flattening_net_fiscal_average	Float64
flattening_ondemand_average	Float64
flattening_usage_average	Float64
net_fiscal_difference	Float64
net_fiscal_difference_pct	Float64
ondemand_difference	Float64
ondemand_difference_pct	Float64
rolling_net_fiscal_average	Float64
rolling_ondemand_average	Float64
rolling_usage_average	Float64
seven_day_net_fiscal	Float64
seven_day_usage	Float64
usage_difference	Float64
usage_difference_pct	Float64
weekly_net_fiscal	Float64
weekly_ondemand	Float64
weekly_usage	Float64

Costs (/costs)

Field Name	Type
billing_unit	String
channel	String
closing_month	DateTime
container_flag	String
cost_category	String
coverable_application_type	String
deployment_age	String
deployment_source	String
disk_type	String
disk_usage_gb	Float64
environment_source	String
gross_fiscal	Float64
instance_type	String
is_actual	String
is_committed_use_eligible	String
lease_ownership_type	String
lease_purchase_month	DateTime
line_item_type	String
migration	String
migration_origin	String
net_cash	Float64
net_fiscal_amount	Float64
ondemand_cost	Float64
operating_system	String
platform	String
product_category	String
product_cost_detail_category	String
propeller_organization	String
reporting_month	String
ri_sp_arn	String
savings	Float64
snapshot_origin	String
steady_state	String
usage_amount	Float64
usage_day	DateTime
usage_type	String

Spend Daily by Account (/costs/spend-daily-by-account)

Field Name	Type
net_fiscal	Float64
ondemand_cost	Float64
usage_amount	Float64
usage_day	DateTime

Spend Daily by Product Account (/costs/spend-daily-by-product)

Field Name	Type
net_fiscal	Float64
ondemand_cost	Float64
product_category	String
product_detail_category	String
product_name	String
usage_amount	Float64
usage_day	DateTime

Spend Monthly by Account (/costs/total-spend-monthly-by-account)

Field Name	Type
month	Float64
total_monthly_net_fiscal	Float64
total_monthly_ondemand_spend	Float64
year	Float64

Spend Monthly by Product (/costs/total-spend-monthly-by-product)

Field Name	Type
month	Float64
product_name	String
total_monthly_net_fiscal	Float64
total_monthly_ondemand_spend	Float64
year	Float64

Discovered Resources (/discovered-resources)

Field Name	Type
business_unit_display_name	String
business_unit_name	String
cloud_account_id	String
configuration	String
cost_rolling_thirty	Float64
is_parking_capable	Boolean
is_running	Boolean
is_snapshot_capable	Boolean
name	String
ostype	String
provider_account_id	String
provider_str	String
region	String
resource_type	String
state	String
tags	String

Recommendation Aging Snapshots (/recommendation-aging-snapshots)

Field Name	Type
age_days	Int64
ami_imageid	String
availabilityzone	String
channel	String
client_type	Int32
est_monthly_net_cash	Float64
est_monthly_ondemand_spend	Float64
has_ami	String
instance_id	String
instance_name	String
location	String
snapshot_age_category	String
snapshot_creation_date	DateTime
snapshot_size	Float64
volume_name	String
volumeid	String
volumetype	String

Recommendation Disk Optimization (/recommendation-disk-optimization)

Field Name	Type
capacity_size	Float64
cost_center	String
current_disk_type	String
current_monthly_total_cost	Float64
current_monthly_total_ondemand	Float64
iops	Float64
monthly_optimal_ondemand_savings	Float64
monthly_optimal_total_savings	Float64
optimal_disk_upgrade	String
optimal_monthly_total_cost	Float64
optimal_ondemand_total_cost	Float64
optimal_upgrade	String
resource_group	String
resource_type	String
throughput	Int32

Recommendation Family Refresh (/recommendation-family-refresh)

Field Name	Type
amd_instance_family	String
amd_instance_type	String
amd_memory	Float64
amd_ondemand_cost	Float64
amd_vcpu	Float64
arm_instance_family	String
arm_instance_type	String
arm_memory	Float64
arm_ondemand_cost	Float64
arm_vcpu	Float64
autoscaling_group_name	String
burstable_instance_family	String
burstable_instance_type	String
burstable_memory	Float64
burstable_ondemand_cost	Float64
burstable_vcpu	Float64
cleaned_environment	String
container_flag	String
cross_family_refresh_right_size_instance_family	String
cross_family_refresh_right_size_instance_type	String
cross_family_refresh_right_size_memory	Float64
cross_family_refresh_right_size_ondemand_cost	Float64
cross_family_refresh_right_size_vcpu	Float64
database_engine_version	String
family_refresh_instance_family	String
family_refresh_instance_type	String
family_refresh_memory	Float64
family_refresh_ondemand_cost	Float64
family_refresh_right_size_instance_family	String
family_refresh_right_size_instance_type	String
family_refresh_right_size_memory	Float64
family_refresh_right_size_ondemand_cost	Float64
family_refresh_right_size_vcpu	Float64
family_refresh_vcpu	Float64
has_autoscaling_group	String
intel_instance_family	String
intel_instance_type	String
intel_memory	Float64
intel_ondemand_cost	Float64
intel_vcpu	Float64
last_day_used	DateTime
max_cpu	Float64
max_memory	Float64
monthly_net_fiscal	Float64
monthly_usage_amount	Float64
optimal_monthly_savings	Float64
optimal_refresh_instance_family	String
optimal_refresh_instance_type	String
optimal_refresh_memory	Float64
optimal_refresh_type	String
optimal_refresh_vcpu	Float64
optimal_savings_pct	Float64
original_instance_family	String
original_instance_family_processor	String
original_instance_type	String
original_memory	Float64
original_ondemand_cost	Float64
original_vcpu	Float64
product_name	String
projected_amd_monthly_savings	Float64
projected_arm_monthly_savings	Float64
projected_burstable_monthly_savings	Float64
projected_cross_family_refresh_right_size_monthly_savings	Float64
projected_family_refresh_and_right_size_monthly_savings	Float64
projected_family_refresh_monthly_savings	Float64
projected_intel_monthly_savings	Float64
projected_right_size_monthly_savings	Float64
right_size_instance_family	String
right_size_instance_type	String
right_size_memory	Float64
right_size_ondemand_cost	Float64
right_size_vcpu	Float64
tenancy	String

Recommendation Idle Databases (/recommendation-idle-databases)

Field Name	Type
autoscaling_group_name	String
bill_payer_account_id	String
cleaned_environment	String
container_flag	String
current_month_running_hours	Float64
database_edition	String
date_first_reported_idle	DateTime
date_last_checked	DateTime
deployment_option	String
discovered_date	DateTime
has_autoscaling_group	String
last_billed_date	DateTime
license_model	String
location_from	String
migration	String
migration_origin	String
net_fiscal	Float64
ondemand_cost	Float64
operating_system	String
propeller_organization	String
resource_type	String
technical_team_name	String
total_days_idle	Float64

Recommendations (/recommendations)

Field Name	Type
additional_metric	String
additional_metric_description	String
billing_unit	String
cost_category	String
cpu_maximum	Float64
has_autoscaling_group	String
instance_type	String
last_usage_day	DateTime
location	String
mem_maximum	Float64
memory	Float64
net_fiscal_cost	Float64
net_savings	Float64
ondemand_cost	Float64
product	String
product_category	String
product_detail_category	String
projected_cost	Float64
rec1_instance_type	String
rec1_net_savings	Float64
rec1_ondemand_savings	Float64
rec1_type	String
rec2_instance_type	String
rec2_net_savings	Float64
rec2_ondemand_savings	Float64
rec2_type	String
rec3_instance_type	String
rec3_net_savings	Float64
rec3_ondemand_savings	Float64
rec3_type	String
rec4_instance_type	String
rec4_net_savings	Float64
rec4_ondemand_savings	Float64
rec4_type	String
rec5_instance_type	String
rec5_net_savings	Float64
rec5_ondemand_savings	Float64
rec5_type	String
rec6_instance_type	String
rec6_net_savings	Float64
rec6_ondemand_savings	Float64
rec6_type	String
rec7_instance_type	String
rec7_net_savings	Float64
rec7_ondemand_savings	Float64
rec7_type	String
rec_type	String
usage_amount	Float64
vcpu	Float64

Reserved Instances (/reserved-instances)

Field Name	Type
benefit_id	String
benefit_name	String
benefit_type	String
bill_payer_account_id	String
estimated_expiration_date	DateTime
minimum_capacity_date	DateTime
monthly_reservation_cost	Float64
term	Int64
total_reservation_cost	Float64

Tags (/tags)

Field Name	Type
container_flag	String
steady_state	String
tag_key	String
tag_value	String

Query Endpoint

The /query endpoint allows you to execute SQL-style queries against the data models. This provides more flexibility than the standard REST endpoints.

Request Format

{
  "query": "SELECT cloud_provider, SUM(gross_fiscal) FROM cost GROUP BY cloud_provider",
  "limit": 100
}

Important Notes

• SQL joins are not supported.
• Remove all extra spaces and semicolons (;) from your query.
• Queries are limited to 100 records by default (this can be changed with the limit parameter).
• The query must be a valid SELECT statement.

Example Queries

SELECT cloud_provider, SUM(gross_fiscal) FROM cost GROUP BY cloud_provider

SELECT product, COUNT(*) FROM recommendation WHERE savings > 1000 GROUP BY product

Error Handling

API errors follow a standard JSON format:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid filter parameter",
  "errors": [
    {
      "location": "query.filter_by",
      "message": "Invalid operator: '=='",
      "value": "status:==:active"
    }
  ]
}

Error responses include:

• HTTP status code
• Error title
• Detailed error message
• A list of specific errors (when applicable)

Example Requests

Get Cost Data with Filtering and Sorting

GET /costs?page=1&size=10&sort_by=net_fiscal_amount:desc&filter_by=cloud_provider:=:AWS,usage_day:between:20230101-20230131

Query Total Spend by Cloud Provider

POST /query
{
  "query": "SELECT cloud_provider, SUM(net_fiscal_amount) as total_spend FROM cost WHERE usage_day BETWEEN '2023-01-01' AND '2023-01-31' GROUP BY cloud_provider ORDER BY total_spend DESC",
  "limit": 10
}

Get Recommendations with Potential Savings

GET /recommendations?filter_by=savings:>:1000,cloud_provider:=:AWS&sort_by=savings:desc

Interpreting HTTP Error Codes

Status Code	Description	Reasons
400	Bad Request	- Invalid sort parameter format (e.g., not "field:order") - Invalid sort order (not "asc" or "desc") - Invalid filter parameter format - Invalid filter operator - Invalid filter field - Invalid date range format - Empty query in data query handler - Invalid query structure
401	Unauthorized	- Missing JWT token - Invalid API key - Expired credentials
403	Forbidden	- User not authorized to access requested business unit data - User lacks permission for the requested operation - Valid authentication but insufficient authorization
404	Not Found	- Requested endpoint doesn't exist - Requested resource not found
422	Unprocessable Entity	- Malformed request body - Required parameters missing - Parameter validation failures
500	Internal Server Error	- Panic recovery (explicitly set in tracelogging middleware) - Database connection failures - Query execution errors - Cache errors - Unexpected system errors
503	Service Unavailable	- Database service unavailable - Dependent services unreachable

---

This documentation provides a comprehensive guide to using the Vega Data API. For specific field information and data model schema details, use the /query/schema endpoint to retrieve up-to-date information about the available fields and models.