# Get usage analytics

Get usage analytics for your organization at different time granularities: yearly, monthly, daily, or hourly.

## Yearly Usage

Get multi-year usage trends and patterns for comprehensive analysis.

#### Path Parameters

**`org_id`** string required

The organization ID.

#### Query Parameters

**`years`** integer optional

Number of years to include (1-10, default: 3).

## Monthly Usage

Get month-by-month usage breakdown for detailed trend analysis.

#### Path Parameters

**`org_id`** string required

The organization ID.

#### Query Parameters

**`year`** integer required

Year to analyze (2020-2030).

**`month`** integer optional

Month for validation (1-12).

**`months`** integer optional

Number of months to include (1-24, default: 12).

## Daily Usage

Get day-by-day usage breakdown for operational monitoring.

#### Path Parameters

**`org_id`** string required

The organization ID.

#### Query Parameters

**`year`** integer required

Year (2020-2030).

**`month`** integer required

Month (1-12).

## Hourly Usage

Get hour-by-hour usage patterns for real-time monitoring.

#### Path Parameters

**`org_id`** string required

The organization ID.

#### Query Parameters

**`date`** string required

Date in YYYY-MM-DD format.

## Returns

All endpoints return usage data with costs in CHF, request counts, synapses, tokens/neurons, and relevant growth rates or patterns.

Yearly

```bash cURL
curl "https://api.aitronos.com/v1/analytics/usage/yearly/org_abc123?years=2" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]
org_id = "org_abc123"

response = requests.get(
    f"https://api.aitronos.com/v1/analytics/usage/yearly/{org_id}",
    params={"years": 2},
    headers={"X-API-Key": api_key}
)

data = response.json()
print(f"Total cost: {data['totalCost']} CHF")
```


```javascript JavaScript
const response = await fetch(
  "https://api.aitronos.com/v1/analytics/usage/yearly/org_abc123?years=2",
  {
    headers: {
      "X-API-Key": process.env.FREDDY_API_KEY
    }
  }
);

const data = await response.json();
console.log(`Total cost: ${data.totalCost} CHF`);
```

**Response:**


```json 200 OK
{
  "organization_id": "org_abc123",
  "period": "yearly",
  "data": [
    {
      "year": 2025,
      "total_cost_chf": 12500.50,
      "total_requests": 50000,
      "total_synapses": 25000000.0,
      "total_tokens": 5000000,
      "growth_rate_percent": 15.2
    },
    {
      "year": 2024,
      "total_cost_chf": 10870.25,
      "total_requests": 45000,
      "total_synapses": 22500000.0,
      "total_tokens": 4500000,
      "growth_rate_percent": null
    }
  ],
  "totalRequests": 95000,
  "totalCost": 23370.75,
  "summary": {
    "start_year": 2024,
    "end_year": 2025,
    "years_included": 2,
    "currency": "CHF"
  }
}
```

Monthly

```bash cURL
curl "https://api.aitronos.com/v1/analytics/usage/monthly/org_abc123?year=2025&months=6" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]
org_id = "org_abc123"

response = requests.get(
    f"https://api.aitronos.com/v1/analytics/usage/monthly/{org_id}",
    params={"year": 2025, "months": 6},
    headers={"X-API-Key": api_key}
)

data = response.json()
print(f"Total requests: {data['totalRequests']}")
```


```javascript JavaScript
const response = await fetch(
  "https://api.aitronos.com/v1/analytics/usage/monthly/org_abc123?year=2025&months=6",
  {
    headers: {
      "X-API-Key": process.env.FREDDY_API_KEY
    }
  }
);

const data = await response.json();
console.log(`Total requests: ${data.totalRequests}`);
```

**Response:**


```json 200 OK
{
  "organization_id": "org_abc123",
  "period": "monthly",
  "data": [
    {
      "month": 11,
      "year": 2025,
      "month_name": "November",
      "total_cost_chf": 1250.75,
      "total_requests": 5000,
      "total_synapses": 2500000.0,
      "total_tokens": 500000,
      "growth_rate_percent": -5.2
    },
    {
      "month": 10,
      "year": 2025,
      "month_name": "October",
      "total_cost_chf": 1320.50,
      "total_requests": 5280,
      "total_synapses": 2640000.0,
      "total_tokens": 528000,
      "growth_rate_percent": 8.5
    }
  ],
  "totalRequests": 10280,
  "totalCost": 2571.25,
  "summary": {
    "year": 2025,
    "start_month": 6,
    "end_month": 11,
    "months_included": 6,
    "currency": "CHF"
  }
}
```

Daily

```bash cURL
curl "https://api.aitronos.com/v1/analytics/usage/daily/org_abc123?year=2025&month=11" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]
org_id = "org_abc123"

response = requests.get(
    f"https://api.aitronos.com/v1/analytics/usage/daily/{org_id}",
    params={"year": 2025, "month": 11},
    headers={"X-API-Key": api_key}
)

data = response.json()
print(f"Peak day: {data['summary']['peak_day']}")
```


```javascript JavaScript
const response = await fetch(
  "https://api.aitronos.com/v1/analytics/usage/daily/org_abc123?year=2025&month=11",
  {
    headers: {
      "X-API-Key": process.env.FREDDY_API_KEY
    }
  }
);

const data = await response.json();
console.log(`Peak day: ${data.summary.peak_day}`);
```

**Response:**


```json 200 OK
{
  "organization_id": "org_abc123",
  "period": "daily",
  "data": [
    {
      "date": "2025-11-01",
      "day_of_week": "Friday",
      "day_of_month": 1,
      "total_requests": 1250,
      "total_cost_chf": 312.50,
      "total_synapses": 625000.0,
      "total_neurons": 12500.0,
      "has_data": true
    },
    {
      "date": "2025-11-02",
      "day_of_week": "Saturday",
      "day_of_month": 2,
      "total_requests": 850,
      "total_cost_chf": 212.50,
      "total_synapses": 425000.0,
      "total_neurons": 8500.0,
      "has_data": true
    }
  ],
  "totalRequests": 2100,
  "totalCost": 525.00,
  "summary": {
    "month": 11,
    "year": 2025,
    "total_days": 30,
    "average_cost_per_day": 17.50,
    "peak_day": "2025-11-15",
    "currency": "CHF"
  }
}
```

Hourly

```bash cURL
curl "https://api.aitronos.com/v1/analytics/usage/hourly/org_abc123?date=2025-11-15" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]
org_id = "org_abc123"

response = requests.get(
    f"https://api.aitronos.com/v1/analytics/usage/hourly/{org_id}",
    params={"date": "2025-11-15"},
    headers={"X-API-Key": api_key}
)

data = response.json()
print(f"Peak hour: {data['summary']['peak_hour']}:00")
```


```javascript JavaScript
const response = await fetch(
  "https://api.aitronos.com/v1/analytics/usage/hourly/org_abc123?date=2025-11-15",
  {
    headers: {
      "X-API-Key": process.env.FREDDY_API_KEY
    }
  }
);

const data = await response.json();
console.log(`Peak hour: ${data.summary.peak_hour}:00`);
```

**Response:**


```json 200 OK
{
  "organization_id": "org_abc123",
  "period": "hourly",
  "data": [
    {
      "hour": 9,
      "hour_display": "09:00",
      "total_requests": 150,
      "total_cost_chf": 37.50,
      "total_synapses": 75000.0,
      "total_neurons": 1500.0,
      "has_data": true
    },
    {
      "hour": 10,
      "hour_display": "10:00",
      "total_requests": 200,
      "total_cost_chf": 50.00,
      "total_synapses": 100000.0,
      "total_neurons": 2000.0,
      "has_data": true
    }
  ],
  "totalRequests": 350,
  "totalCost": 87.50,
  "summary": {
    "date": "2025-11-15",
    "avg_requests_per_hour": 175.0,
    "hours_with_activity": 12,
    "peak_hour": 14,
    "currency": "CHF"
  }
}
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required",
    "system_message": "No API key provided",
    "type": "client_error",
    "status": 401,
    "trace_id": "abc-123-def",
    "timestamp": "2025-11-15T10:30:00Z"
  }
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "ORGANIZATION_ACCESS_DENIED",
    "message": "Access denied to organization",
    "system_message": "API key doesn't belong to organization",
    "type": "authorization_error",
    "status": 403,
    "trace_id": "def-456-ghi",
    "timestamp": "2025-11-15T10:30:00Z"
  }
}
```


```json 400 Bad Request
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid query parameters",
    "system_message": "Validation error details",
    "type": "validation_error",
    "status": 400,
    "trace_id": "ghi-789-jkl",
    "timestamp": "2025-11-15T10:30:00Z"
  }
}
```


```json 500 Server Error
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred",
    "system_message": "Database query failed",
    "type": "server_error",
    "status": 500,
    "trace_id": "jkl-012-mno",
    "timestamp": "2025-11-15T10:30:00Z"
  }
}
```