Usage Logs Reference

The Usage Logs API provides endpoints for querying service instance usage metrics. Queries are scoped to specific service instances and capture detailed request/response data for operational monitoring and troubleshooting.

API Reference

The Usage Logs API exposes RESTful endpoints for querying service instance logs. The API provides endpoints for:

• Initiating queries: Submit a query with date range and optional HTTP method filter for a specific service instance
• Retrieving results: Poll for query results using a query execution ID with pagination support

For detailed API documentation, including request/response formats, error codes, and complete endpoint specifications, see the API Reference.

Query Operations

The Usage Logs API supports two primary operations:

Operation	Endpoint	Method	Purpose
Initiate Query	/{service}/{instanceResourceId}	POST	Start a new usage log query for a service instance
Get Query Results	/{service}/{instanceResourceId}/query-result/{queryExecutionId}	GET	Retrieve results from a completed query

Query Parameters

All queries accept the following parameters:

Request body (Initiate Query)

{
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-02T00:00:00Z",
    "method": "GET",
    "nextToken": "optional-pagination-token"
}

• from (required): ISO 8601 start date-time for the query window
• to (required): ISO 8601 end date-time for the query window
• method (optional): Filter by HTTP method (GET, POST, PUT, DELETE, PATCH)
• nextToken (optional): Pagination token from previous result set

Response (Initiate Query)

{
    "queryExecutionId": "unique-query-execution-identifier"
}

Response (Get Query Results)

{
    "data": [
        {
            "account_id": "string",
            "service": "string",
            "instance_id": "string",
            "metadata": {
                "id": "uuid",
                "requestId": "string",
                "version": "1.0",
                "region": "global|eu",
                "scope": "management|service"
            },
            "request": {
                "auth": {
                    "method": "string",
                    "publicKey": "string"
                },
                "method": "GET|POST|PUT|DELETE|PATCH",
                "path": "string",
                "originalUrl": "string",
                "hostname": "string",
                "headers": {},
                "query": {},
                "body": "any"
            },
            "response": {
                "statusCode": "number",
                "headers": {},
                "body": "any"
            },
            "timestamp": "number"
        }
    ],
    "nextToken": "optional-pagination-token"
}

Service Instances

Usage logs queries require a specific service instance. Valid service values include:

• authorizer
• gateway
• library
• logs
• resolver
• validator
• verifier
• accounts
• iam

Error Responses

The Usage Logs API returns standard error responses:

Status	Error	Description
400	Bad request error	Invalid query parameters or request format
401	Unauthorized	Missing or invalid authentication
404	Resource not found	Service instance or query execution ID not found
500	Internal server error	Unexpected server error

Related documentation

• Usage Logs Explanation: Conceptual understanding of usage logs
• Trail Logs Reference: Audit trail log query endpoints