Trail Logs Reference

The Trail Logs API provides endpoints for querying system-wide audit data. Queries are scoped to your entire account and capture request/response details across all services for compliance, auditing, and system-wide analysis.

API Reference

The Trail Logs API exposes RESTful endpoints for querying account-wide audit trails. The API provides endpoints for:

Initiating queries: Submit a query with date range and optional HTTP method filter to search across all services
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 Trail Logs API supports two primary operations:

Operation	Endpoint	Method	Purpose
Initiate Query	`/`	POST	Start a new trail log query for your account
Get Query Results	`/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",
            "metadata": {
                "id": "uuid",
                "requestId": "string",
                "version": "1.0",
                "region": "global|eu",
                "scope": "management|service",
                "service": "string"
            },
            "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"
}

Query Scope

Trail logs queries return audit data across your entire account:

Account-wide: Queries span all services and instances
Cross-service: See activities across authorizer, gateway, resolver, validator, verifier, and management services
Organization perspective: Understand system-wide patterns and compliance activities

Error Responses

The Trail 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	Query execution ID not found
500	Internal server error	Unexpected server error

Trail Logs Explanation: Conceptual understanding of trail logs
Usage Logs Reference: Service instance usage log query endpoints