📊 Logs API: How to Use It

Access API usage logs for monitoring, auditing, and insights

The Clara Logs API offers structured access to historical API logs, allowing clients to retrieve request-level data and usage statistics within a defined temporal scope. This is especially useful for monitoring, auditing, billing analytics, and debugging purposes.

🔐 Access Control

• Logs API access is restricted by design.
• Requests must include date-based filters: year, month, and optionally day.
• No endpoint available to list all logs without any time constraint.

📌 Endpoints Overview

Endpoint	Description
/api/v1/logs/yyyy/MM	Get logs for a specific month (year and month required).
/api/v1/logs/yyyy/MM/dd	Get logs for a specific day.
/api/v1/logs/current	Get logs for the current month.

🔎 Filtering Rules

• year and month required
• day-level filtering is optional
• No wildcard or unbounded access to the full log history.

This structure ensures controlled data volumes and better performance.

📦 Response Structure

Every response contains two main components:

1️⃣ Stats:

• total: Total number of requests
• chargeable: Number of requests marked as chargeable
• nonChargeable: Requests that are not chargeable

2️⃣ Requests (list of detailed logs):

• id: Unique identifier of the log entry
• responseStatus: HTTP status code returned
• projectTokenId: Project identifier for the request
• requestUri: URI requested by the client
• method: HTTP method used (GET, POST, etc)
• chargeable: Boolean flag indicating billing impact
• instant: Timestamp of the request (epoch milliseconds)

🧾 Example Response

JSON

{
  "stats": {
    "total": 1,
    "chargeable": 1,
    "nonChargeable": 0
  },
  "requests": [
    {
      "id": "1",
      "responseStatus": "200",
      "projectTokenId": "project-123",
      "requestUri": "/api/v1/charge",
      "method": "POST",
      "chargeable": true,
      "instant": 123141241
    }
  ]
}