Access Trail Logs

This guide walks you through querying trail logs to retrieve system-wide audit data across your entire Vidos account.

Prerequisites

A Vidos account with appropriate permissions
An API key with access to the logs management API
At least one deployed service instance (to generate audit data)

Understanding trail logs

Trail logs capture system-wide audit data across your entire Vidos infrastructure. Each log entry includes:

HTTP request and response details
Authentication method and context
Service and operation information
Timestamp of the operation
Complete request/response headers and body content

Trail logs are scoped to your entire account, enabling organization-wide compliance, auditing, and troubleshooting.

Query trail logs

Trail logs use an asynchronous query model. You initiate a query and then poll for results:

Step 1: Initiate a query

Send a POST request to initiate a trail log query for your account:

curl -X POST https://trail.management.global.vidos.id/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-02T00:00:00Z",
    "method": "POST"
  }'

Request parameters:

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)

Response:

{
    "queryExecutionId": "trail-123-abc-456"
}

Store the queryExecutionId to retrieve results.

Step 2: Poll for results

Use the query execution ID to retrieve results:

curl -X GET https://trail.management.global.vidos.id/query-result/trail-123-abc-456 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
    "data": [
        {
            "account_id": "acc_12345",
            "metadata": {
                "id": "550e8400-e29b-41d4-a716-446655440000",
                "requestId": "req_trail123",
                "version": "1.0",
                "region": "global",
                "scope": "management",
                "service": "authorizer"
            },
            "request": {
                "method": "POST",
                "path": "/api/authorize",
                "auth": {
                    "method": "api-key",
                    "publicKey": "pk_admin001"
                },
                "headers": {},
                "query": {}
            },
            "response": {
                "statusCode": 200,
                "headers": {}
            },
            "timestamp": 1704067200000
        }
    ],
    "nextToken": "next_page_token"
}

Step 3: Handle pagination

If your result set is large, use the nextToken to retrieve the next page:

curl -X GET "https://trail.management.global.vidos.id/query-result/trail-123-abc-456?nextToken=next_page_token" \
  -H "Authorization: Bearer YOUR_API_KEY"

Continue polling until nextToken is not returned, indicating you’ve reached the end of results.

Common audit patterns

Query all account activity in the past week

Monitor your account’s overall activity:

FROM=$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ)
TO=$(date -u +%Y-%m-%dT%H:%M:%SZ)

curl -X POST https://trail.management.global.vidos.id/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"from\": \"$FROM\",
    \"to\": \"$TO\"
  }"

Find failed operations

Query for operations that returned error status codes:

curl -X POST https://trail.management.global.vidos.id/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-02T00:00:00Z"
  }' | jq '.data[] | select(.response.statusCode >= 400)'

Track all management operations

Monitor configuration changes and administrative actions:

curl -X POST https://trail.management.global.vidos.id/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-02T00:00:00Z",
    "method": "POST"
  }' | jq '.data[] | select(.metadata.scope == "management")'

Audit by service

Find all operations that touched a specific service:

QUERY_ID="trail-123-abc-456"

curl -X GET "https://trail.management.global.vidos.id/query-result/$QUERY_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" | \
  jq ".data[] | select(.metadata.service == \"resolver\")"

Compliance date range query

Query a specific compliance period for auditing:

curl -X POST https://trail.management.global.vidos.id/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2023-Q4-01T00:00:00Z",
    "to": "2023-12-31T23:59:59Z"
  }'

Verify your query

You have successfully queried trail logs when:

HTTP status is 201 for initiation or 200 for results retrieval
queryExecutionId is returned from the initiation request
data array contains log entries across your account’s services
Each log entry includes request, response, and metadata fields
Results span multiple services and operations

Security and compliance

Trail logs support your compliance requirements:

Immutable audit trail: All operations are captured and cannot be modified
Account-level scope: Logs include all activities across your infrastructure
Detailed context: Complete request/response data for investigation
Time-based queries: Easily retrieve logs for specific compliance periods
Access control: Only users with appropriate permissions can query trail logs

Troubleshooting

Issue	Solution
Empty `data` array	No operations occurred during the specified time window, or time range is too narrow
Query timeout	Try with a smaller time range or check that dates are in ISO 8601 format
”Unauthorized” error	Verify your API key is valid and has access to the trail logs API
”Invalid time range” error	Ensure `from` is before `to` and both are in ISO 8601 format
High volume of results	Use `nextToken` for pagination or narrow the time window
Cannot find specific operation	Verify the service name and method; check that the operation occurred within the time range

Understanding Trail Logs: Conceptual overview
Trail Logs API Reference: Complete API documentation
Create API Key: Generate authentication credentials
Understanding Logs Management: Overview of both trail and usage logs