# Usage

## Get Usage Stats

> Get daily usage statistics for the API key's organization.\
> \
> Returns paginated daily usage statistics with optional filtering by date range,\
> model, provider, and source. Each record represents aggregated usage for a specific\
> user/model/provider/source combination on a given date.

```json
{"openapi":"3.1.0","info":{"title":"AFM API - External API","version":"0.1.0"},"paths":{"/api/v1/usage/stats":{"get":{"tags":["Usage"],"summary":"Get Usage Stats","description":"Get daily usage statistics for the API key's organization.\n\nReturns paginated daily usage statistics with optional filtering by date range,\nmodel, provider, and source. Each record represents aggregated usage for a specific\nuser/model/provider/source combination on a given date.","operationId":"get_usage_stats_api_v1_usage_stats_get","parameters":[{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Start date for filtering (ISO format)"},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"End date for filtering (ISO format)"},{"name":"model","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by specific model"},{"name":"model_provider","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by model provider"},{"name":"source","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by source (api or app)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Number of records to return","default":100,"title":"Limit"},"description":"Number of records to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip","default":0,"title":"Offset"},"description":"Number of records to skip"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UsageStatsResponse"},"title":"Response Get Usage Stats Api V1 Usage Stats Get"}}}},"401":{"description":"Authentication Fails","content":{"application/json":{}}},"422":{"description":"Invalid Parameters","content":{"application/json":{}}},"500":{"description":"Server Error","content":{"application/json":{}}}}}}},"components":{"schemas":{"UsageStatsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"user_id":{"type":"string","format":"uuid","title":"User Id"},"org_id":{"type":"string","format":"uuid","title":"Org Id"},"email":{"type":"string"},"model":{"type":"string","title":"Model"},"source":{"type":"string","title":"Source"},"input_tokens":{"type":"integer","title":"Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"total_tokens":{"type":"integer","title":"Total Tokens"},"total_requests":{"type":"integer","title":"Total Requests"},"date":{"type":"string","format":"date-time","title":"Date"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","user_id","org_id","email","model","source","input_tokens","output_tokens","total_tokens","total_requests","date","created_at"],"title":"UsageStatsResponse","description":"API response model for daily usage statistics."}}}}
```

## Get Usage Summary

> Get aggregated usage summary statistics for the API key's organization.\
> \
> Returns high-level metrics including total tokens, requests, unique users,\
> models, providers, and breakdown by API vs app usage.

```json
{"openapi":"3.1.0","info":{"title":"AFM API - External API","version":"0.1.0"},"paths":{"/api/v1/usage/summary":{"get":{"tags":["Usage"],"summary":"Get Usage Summary","description":"Get aggregated usage summary statistics for the API key's organization.\n\nReturns high-level metrics including total tokens, requests, unique users,\nmodels, providers, and breakdown by API vs app usage.","operationId":"get_usage_summary_api_v1_usage_summary_get","parameters":[{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Start date for summary (ISO format)"},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"End date for summary (ISO format)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api_external__usage__models__UsageSummaryResponse"}}}},"401":{"description":"Authentication Fails","content":{"application/json":{}}},"422":{"description":"Invalid Parameters","content":{"application/json":{}}},"500":{"description":"Server Error","content":{"application/json":{}}}}}}},"components":{"schemas":{"api_external__usage__models__UsageSummaryResponse":{"properties":{"total_input_tokens":{"type":"integer","title":"Total Input Tokens"},"total_output_tokens":{"type":"integer","title":"Total Output Tokens"},"total_tokens":{"type":"integer","title":"Total Tokens"},"total_requests":{"type":"integer","title":"Total Requests"},"unique_users":{"type":"integer","title":"Unique Users"},"unique_models":{"type":"integer","title":"Unique Models"},"unique_providers":{"type":"integer","title":"Unique Providers"},"api_usage":{"type":"integer","title":"Api Usage"},"app_usage":{"type":"integer","title":"App Usage"},"date_range_days":{"type":"integer","title":"Date Range Days"}},"type":"object","required":["total_input_tokens","total_output_tokens","total_tokens","total_requests","unique_users","unique_models","unique_providers","api_usage","app_usage","date_range_days"],"title":"UsageSummaryResponse","description":"API response model for aggregated usage summary."}}}}
```