---
updatedAt: 2025-12-16T10:02:04.000Z
agentTools:
  siteIndex: https://docs.here.com/llms.txt
  projectIndex: https://docs.here.com/usage/llms.txt
---

# Download a usage report

  This API downloads the created usage report. 
  * The API responds with the usage report encoded in gzip format. 
  * The API supports usage by app ID.

# OpenAPI definition

```json
{
  "openapi": "3.0.2",
  "info": {
    "version": "2.2.0",
    "title": "Cost Management Usage API v2",
    "description": "Provides API reference details for Usage API v2 which you can use to retrieve billable usage information. Usage billing rates are dependent on your licensing terms.",
    "termsOfService": "https://developer.here.com/terms-conditions",
    "license": {
      "name": "HERE Documentation License",
      "url": "https://legal.here.com/en-gb/terms/documentation-license"
    }
  },
  "externalDocs": {
    "description": "The developer guide and release notes are available here.",
    "url": "https://www.here.com/docs/category/cost-management"
  },
  "servers": [
    {
      "url": "https://usage.bam.api.here.com/v2",
      "description": "Production server."
    }
  ],
  "tags": [
    {
      "name": "Usage",
      "description": "Usage"
    }
  ],
  "paths": {
    "/usage/realms/{realmId}/reports/{reportId}/output": {
      "get": {
        "summary": "Download a usage report",
        "description": "  This API downloads the created usage report. \n  * The API responds with the usage report encoded in gzip format. \n  * The API supports usage by app ID.",
        "operationId": "fetchCreatedReport",
        "tags": [
          "Usage"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Realm"
          },
          {
            "$ref": "#/components/parameters/ReportId"
          },
          {
            "$ref": "#/components/parameters/xRequestId"
          },
          {
            "$ref": "#/components/parameters/xCorrelationId"
          }
        ],
        "security": [
          {
            "token": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response.",
            "headers": {
              "X-Correlation-ID": {
                "$ref": "#/components/headers/XCorrelationId"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            },
            "content": {
              "application/x-gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "description": "The usage report output is in gzip file format.",
                  "example": "REPORT-1583.csv.gz"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "description": "Get usage report.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "examples": {
      "InvalidRealm": {
        "value": {
          "title": "Input data failed validation",
          "errorId": "ERROR-9d862c5a-4cfd-4780-8be4-2728b42849e1",
          "status": 400,
          "code": "E706001",
          "cause": "Invalid Realm",
          "action": "Correct input data and retry request",
          "correlationId": "4199533b-6290-41db-8d79-edf4f4019a74",
          "details": {
            "title": "Invalid Realm {realm}",
            "message": "Realm  {realm} has invalid characters."
          }
        }
      },
      "InvalidLimit": {
        "value": {
          "title": "Input data failed validation",
          "errorId": "ERROR-22862c5a-4cfd-4780-8be4-2728b42de3j",
          "status": 400,
          "code": "E706002",
          "cause": "Invalid Limit",
          "action": "Correct input data and retry request",
          "correlationId": "4199533b-6290-41db-8d79-edf4f4019a74",
          "details": {
            "title": "Invalid Limit.",
            "message": "Limit value should not be greater than 100."
          }
        }
      },
      "InvalidDateRange": {
        "value": {
          "title": "Input data failed validation",
          "errorId": "ERROR-22862c5a-4cfd-4780-8be4-2728b42de3j",
          "status": 400,
          "code": "E706003",
          "cause": "start or end Date validation failed",
          "action": "Correct input data and retry request",
          "correlationId": "4199533b-6290-41db-8d79-edf4f4019a74",
          "details": {
            "title": "Invalid Start or end date.",
            "message": "Invalid Start or end date."
          }
        }
      },
      "InvalidGroupBy": {
        "value": {
          "title": "Input data failed validation",
          "errorId": "ERROR-22862c5a-4cfd-4780-8be4-2728b42de3j",
          "status": 400,
          "code": "E706004",
          "cause": "Invalid group by field. Supported are appId, billingTag, and project",
          "action": "Correct input data and retry request",
          "correlationId": "4199533b-6290-41db-8d79-edf4f4019a74",
          "details": {
            "title": "Invalid group by field.",
            "message": "Invalid group by field. Supported values are appId, billingTag, and project."
          }
        }
      }
    },
    "parameters": {
      "Realm": {
        "name": "realmId",
        "in": "path",
        "description": "Organization ID.",
        "required": true,
        "example": "olp-here",
        "schema": {
          "type": "string",
          "minLength": 5,
          "maxLength": 30
        }
      },
      "ReportId": {
        "name": "reportId",
        "in": "path",
        "description": "Report ID.",
        "required": true,
        "example": "REPORT-1346",
        "schema": {
          "type": "string",
          "minLength": 11,
          "maxLength": 30
        }
      },
      "xRequestId": {
        "name": "X-Request-ID",
        "in": "header",
        "description": "User-provided token used to trace a request or a group of requests sent to the service.",
        "schema": {
          "type": "string"
        }
      },
      "xCorrelationId": {
        "name": "X-Correlation-ID",
        "in": "header",
        "required": true,
        "description": "Auto-generated ID, which uniquely identifies the request and is in the response. When contacting the support team with an inquiry regarding a specific request, provide the value of this header to assist with troubleshooting.\n",
        "schema": {
          "type": "string"
        }
      }
    },
    "securitySchemes": {
      "token": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "A client access token must be obtained from a separate endpoint using the client credentials and an OAuth 1.0a HMAC-SHA256 signed request.\n\nFor more information, see https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html.\n"
      }
    },
    "responses": {
      "BadRequest": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "InvalidRealm": {
                "$ref": "#/components/examples/InvalidRealm"
              },
              "InvalidLimit": {
                "$ref": "#/components/examples/InvalidLimit"
              },
              "InvalidDateRange": {
                "$ref": "#/components/examples/InvalidDateRange"
              },
              "InvalidGroupBy": {
                "$ref": "#/components/examples/InvalidGroupBy"
              }
            }
          }
        },
        "description": "Invalid input provided, see error response for details.",
        "headers": {
          "X-Correlation-ID": {
            "$ref": "#/components/headers/XCorrelationId"
          },
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      }
    },
    "headers": {
      "X-Request-ID": {
        "description": "User provided token used to trace a request or a group of requests sent to the service.\n",
        "schema": {
          "type": "string"
        }
      },
      "XCorrelationId": {
        "schema": {
          "type": "string"
        },
        "required": false,
        "description": "Correlates HTTP requests between a client and server. Sentry generates the X-Correlation-ID UUID and passes it to downstream services. It generates if it's not present in the incoming request.\n"
      }
    },
    "schemas": {
      "ErrorDetail": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error Code.",
            "example": "ASYNC_API_DISABLED_FOR_USER"
          },
          "title": {
            "type": "string",
            "description": "Error message.",
            "example": "Invalid size value"
          },
          "source": {
            "type": "string",
            "description": "Reference to a JSON path.",
            "example": "$.taFeatures.size"
          },
          "message": {
            "type": "string",
            "description": "Detailed error message.",
            "example": "Size must be between 1 and 3"
          },
          "messageTemplate": {
            "type": "string",
            "description": "Optional error template.",
            "example": "validation.constraint.between"
          },
          "messagePlaceholders": {
            "type": "object",
            "additionalProperties": {},
            "example": {
              "field": "size",
              "min": 1,
              "max": 3
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "title",
          "status",
          "code",
          "cause",
          "action",
          "errorId",
          "correlationId"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Error title.",
            "example": "Input data failed validation"
          },
          "errorId": {
            "type": "string",
            "description": "Unique ID for the error. This is searchable in the TA logs.",
            "example": "ERROR-9d862c5a-4cfd-4780-8be4-2728b42849e1"
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code.",
            "example": 400
          },
          "code": {
            "type": "string",
            "description": "Resource specific error code.",
            "example": "E706XX"
          },
          "cause": {
            "type": "string",
            "description": "The cause of the error.",
            "example": "The input data in question does not meet validation rules."
          },
          "action": {
            "type": "string",
            "description": "Actionable instructions for the API requester.",
            "example": "Correct input data and retry the request."
          },
          "correlationId": {
            "type": "string",
            "description": "Correlation ID.",
            "example": "4199533b-6290-41db-8d79-edf4f4019a74"
          },
          "details": {
            "type": "array",
            "description": "Collection of error details.",
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            }
          }
        }
      }
    }
  }
}
```