# Get yearly usage

Retrieve year-by-year usage breakdown for long-term trend analysis.

#### Path Parameters

**`org_id`** string required

The organization ID.

#### Query Parameters

**`years`** integer

Number of years to retrieve. Default: `2`. Range: 1-10.

## Returns

Returns a [YearlyUsageResponse object](/docs/api-reference/objects/yearly-usage-response-object) with year-by-year usage analytics including costs, requests, and growth rates.


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


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

result = client.analytics_usage.get_yearly_usage(
    org_id="org_abc123",
    years=2,
)
print(result)
```


```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['total_cost']} CHF")
```


```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.total_cost} CHF`);
```

**Response:**

200 OK

```json
{
  "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
    }
  ],
  "total_requests": 95000,
  "total_cost": 23370.75,
  "summary": {
    "start_year": 2024,
    "end_year": 2025,
    "years_included": 2,
    "currency": "CHF"
  }
}
```

401 Unauthorized

```json
{
  "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",
    "details": {}
  }
}
```

403 Forbidden

```json
{
  "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",
    "details": {}
  }
}
```

400 Bad Request

```json
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid query parameters",
    "system_message": "years must be between 1 and 10",
    "type": "validation_error",
    "status": 400,
    "trace_id": "ghi-789-jkl",
    "timestamp": "2025-11-15T10:30:00Z",
    "details": {}
  }
}
```

500 Server Error

```json
{
  "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",
    "details": {}
  }
}
```

## Related Resources

- [Usage Overview](/docs/api-reference/analytics/usage/get-usage)