> ## Documentation Index
> Fetch the complete documentation index at: https://docs.g-tateth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

Access usage statistics and performance metrics for your tenant's API usage.

## Get Usage Statistics

<Endpoint method="GET" path="/api/v1/analytics/usage">
  Get usage statistics for the current or specified month
</Endpoint>

<ParamField query="month" type="string" optional>
  Month in YYYY-MM format (e.g., "2024-01"). Defaults to current month.
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data.month" type="string">
  Month in YYYY-MM format
</ResponseField>

<ResponseField name="data.usage.totalRequests" type="number">
  Total API requests in the month
</ResponseField>

<ResponseField name="data.usage.requestsByEndpoint" type="object">
  Requests broken down by endpoint path
</ResponseField>

<ResponseField name="data.usage.requestsByMethod" type="object">
  Requests broken down by HTTP method (GET, POST, etc.)
</ResponseField>

<ResponseField name="data.limits.apiCalls" type="number">
  Monthly API call limit from your plan (-1 for unlimited)
</ResponseField>

<ResponseField name="data.limits.isUnlimited" type="boolean">
  Whether the plan has unlimited API calls
</ResponseField>

<ResponseField name="data.overage.requests" type="number">
  Number of requests exceeding the plan limit
</ResponseField>

<ResponseField name="data.overage.percentage" type="number">
  Percentage of limit exceeded
</ResponseField>

### Example Request

```bash theme={null}
curl -X GET "https://api.g-tateth.com/api/v1/analytics/usage?month=2024-01" \
  -H "Authorization: Bearer sk_live_your_api_key"
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "month": "2024-01",
    "usage": {
      "totalRequests": 12500,
      "requestsByEndpoint": {
        "/api/v1/conversations": 8500,
        "/api/v1/customers": 3000,
        "/api/v1/webhooks": 1000
      },
      "requestsByMethod": {
        "GET": 11000,
        "POST": 1000,
        "PUT": 400,
        "DELETE": 100
      }
    },
    "limits": {
      "apiCalls": 10000,
      "isUnlimited": false
    },
    "overage": {
      "requests": 2500,
      "percentage": 25
    }
  }
}
```

## Get Usage History

<Endpoint method="GET" path="/api/v1/analytics/usage/history">
  Get usage statistics for multiple months
</Endpoint>

<ParamField query="months" type="integer" optional>
  Number of months to retrieve (1-24, default: 12)
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data" type="array">
  Array of usage objects, one per month
</ResponseField>

### Example Request

```bash theme={null}
curl -X GET "https://api.g-tateth.com/api/v1/analytics/usage/history?months=6" \
  -H "Authorization: Bearer sk_live_your_api_key"
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "month": "2024-01",
      "totalRequests": 12500,
      "requestsByEndpoint": {
        "/api/v1/conversations": 8500,
        "/api/v1/customers": 3000,
        "/api/v1/webhooks": 1000
      }
    },
    {
      "month": "2023-12",
      "totalRequests": 9800,
      "requestsByEndpoint": {
        "/api/v1/conversations": 6500,
        "/api/v1/customers": 2500,
        "/api/v1/webhooks": 800
      }
    }
  ]
}
```

## Get Performance Metrics

<Endpoint method="GET" path="/api/v1/analytics/metrics">
  Get performance metrics for the current or specified month
</Endpoint>

<ParamField query="month" type="string" optional>
  Month in YYYY-MM format (e.g., "2024-01"). Defaults to current month.
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data.month" type="string">
  Month in YYYY-MM format
</ResponseField>

<ResponseField name="data.averageResponseTime" type="number">
  Average API response time in milliseconds
</ResponseField>

<ResponseField name="data.p95ResponseTime" type="number">
  95th percentile response time in milliseconds
</ResponseField>

<ResponseField name="data.p99ResponseTime" type="number">
  99th percentile response time in milliseconds
</ResponseField>

<ResponseField name="data.errorRate" type="number">
  Percentage of requests that resulted in errors
</ResponseField>

<ResponseField name="data.totalRequests" type="number">
  Total requests in the month
</ResponseField>

<ResponseField name="data.successfulRequests" type="number">
  Number of successful requests (2xx status codes)
</ResponseField>

<ResponseField name="data.failedRequests" type="number">
  Number of failed requests (4xx, 5xx status codes)
</ResponseField>

### Example Request

```bash theme={null}
curl -X GET "https://api.g-tateth.com/api/v1/analytics/metrics?month=2024-01" \
  -H "Authorization: Bearer sk_live_your_api_key"
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "month": "2024-01",
    "averageResponseTime": 125,
    "p95ResponseTime": 250,
    "p99ResponseTime": 500,
    "errorRate": 0.5,
    "totalRequests": 12500,
    "successfulRequests": 12437,
    "failedRequests": 63
  }
}
```

## Required Permissions

* `read:analytics` - Required for all analytics endpoints

<Note>
  Analytics data is aggregated monthly. Historical data is available for up to 24 months.
</Note>