get_app_usage

ReportsApi.get_app_usage(month, role_id, projection_expression=None, latest=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

Get cost and usage for a month

Returns Cost Explorer usage for the month in the path (YYYY-MM). Requires system-settings.view. Future months return GE-1001. latest=yes reads Cost Explorer live and omits LastUpdatedTime. Any other latest value (default no) reads the latest DynamoDB snapshot for that month, or Cost Explorer if none exists.

Parameters:

  • month (str) – Calendar month as YYYY-MM, for example 2020-08. Start is the first day; End is the first day of the next month (Cost Explorer End is exclusive). Greater than the current month returns GE-1001. (required)

  • role_id (str) – Amorphic role ID the request is authorized against. Must be a role the user belongs to. Used for permission checks and audit logs. (required)

  • projection_expression (str) – Comma-separated top-level keys to keep (TimePeriod, EstimatedUsage, CurrentUsage, UsageByService, LastUpdatedTime). Split is not trimmed.

  • latest (str) – Defaults to no. Only the exact value yes uses live Cost Explorer and skips LastUpdatedTime. Any other value uses the DynamoDB snapshot path.

  • _request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.

  • _request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.

  • _content_type (str, Optional) – force content-type for the request.

  • _headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.

  • _host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

GetAppUsageResponse

Returns:

Returns the result object.

Request and Response Examples

HTTP: GET /usage/{month}

Success (HTTP 200)

TimePeriod and EstimatedUsage always unless projection omits them. CurrentUsage and UsageByService from CE or DynamoDB. LastUpdatedTime only when latest is not yes. No properties are required because of projection.

latest omitted, DynamoDB hit

{
  "TimePeriod": {
    "Start": "2026-07-01",
    "End": "2026-08-01"
  },
  "EstimatedUsage": {
    "Amount": "120.50",
    "Unit": "USD"
  },
  "CurrentUsage": {
    "Amount": "98.10",
    "Unit": "USD"
  },
  "UsageByService": [
    {
      "ServiceName": "Amazon Simple Storage Service",
      "BlendedCost": {
        "Amount": "10.00",
        "Unit": "USD"
      },
      "UsageQuantity": {
        "Amount": "100",
        "Unit": "GB"
      }
    }
  ],
  "LastUpdatedTime": "2026-08-01 00:30:12"
}

Errors

Documented error codes: AUTH-1030, GE-1001.

HTTP 400

AUTH-1030 missing system-settings.view. GE-1001 when month is after the current calendar month.

Future month

{
  "Message": "GE-1001 - provided year or month is greater than current year or month"
}

Missing permission

{
  "Message": "AUTH-1030 - User is not authorized to get the app and cost usage stats due to the following missing permission(s) - {'system-settings': ['view']}"
}

HTTP 500

Message is a fixed string. Details is the exception text (including a malformed month path). Forecast failure can still be 200 with EstimatedUsage Amount Unavailable.

Uncaught Exception

{
  "Message": "Something went wrong, try again later.",
  "Details": "invalid literal for int() with base 10: 'foo'"
}