> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augmentcode.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Analytics API Reference
> Detailed API endpoint documentation.
**Preview Feature**
The Analytics API is currently in preview and is available exclusively to Enterprise customers.
**Important: Timezone and Data Availability**
All dates in requests and responses are interpreted and returned in **UTC timezone**. The most recent queryable date is "yesterday" (UTC), and data for the previous day becomes available at approximately **02:00 UTC** each day.
**Data Freshness**
Analytics metrics endpoints (DAU, usage, activity) are updated once daily. Data for a given day becomes available the following day at approximately 02:00 UTC. Budget override endpoints (`get-user-budget-overrides`, `set-user-budget-overrides`) read and write configuration in real time.
## GET /analytics/v0/dau-count
Returns daily active user counts over a date range.
### Query Parameters
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------- |
| start\_date | string | No | Start date in `YYYY-MM-DD` format (UTC) |
| end\_date | string | No | End date in `YYYY-MM-DD` format (UTC) |
### Date Range Behavior
| Scenario | Behavior |
| -------------------------- | -------------------------------------------------------------- |
| Neither date provided | Returns last 7 days ending at yesterday (UTC) |
| Only `start_date` provided | Returns 7 days starting from `start_date`, capped at yesterday |
| Only `end_date` provided | Returns 7 days ending at `end_date` |
| Both dates provided | Returns the specified inclusive range |
### Constraints
| Constraint | Value |
| --------------------------- | ---------------------------------------------------- |
| Maximum date range | 90 days |
| Maximum historical lookback | 2 years |
| Today and future dates | Not allowed (data available at \~02:00 UTC next day) |
| Timezone | All dates interpreted as UTC |
### Example Request
```bash theme={null}
curl -X GET "https://api.augmentcode.com/analytics/v0/dau-count?start_date=2025-10-15&end_date=2025-10-20" \
-H "Authorization: Bearer "
```
### Example Response
```json theme={null}
{
"daily_active_user_counts": [
{"date": "2025-10-15", "user_count": 100},
{"date": "2025-10-16", "user_count": 120},
{"date": "2025-10-17", "user_count": 95},
{"date": "2025-10-18", "user_count": 140},
{"date": "2025-10-19", "user_count": 88},
{"date": "2025-10-20", "user_count": 110}
],
"metadata": {
"effective_start_date": "2025-10-15",
"effective_end_date": "2025-10-20",
"generated_at": "2025-10-21T10:30:00Z",
"total_days": 6
}
}
```
### Response Fields
| Field | Type | Description |
| ------------------------------------------ | ------- | ----------------------------------------------------- |
| daily\_active\_user\_counts | array | Array of daily user counts, one per day |
| daily\_active\_user\_counts\[].date | string | Calendar date (`YYYY-MM-DD`) |
| daily\_active\_user\_counts\[].user\_count | integer | Number of unique active users |
| metadata.effective\_start\_date | string | Actual start date used (UTC, after defaults/clamping) |
| metadata.effective\_end\_date | string | Actual end date used (UTC, after defaults/clamping) |
| metadata.generated\_at | string | Response generation timestamp (ISO 8601) |
| metadata.total\_days | integer | Number of days in the range |
***
## GET /analytics/v0/dau
Returns the list of active users for a specific date. Supports pagination.
### Query Parameters
| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ------------------------------------------ |
| date | string | No | Date to query in `YYYY-MM-DD` format (UTC) |
| cursor | string | No | Pagination cursor from previous response |
| page\_size | integer | No | Number of results per page |
### Date Behavior
| Scenario | Behavior |
| ----------------- | ---------------------------------------------------------------- |
| Date not provided | Defaults to yesterday (UTC) |
| Date provided | Returns users active on that date (must be yesterday or earlier) |
### Pagination
| Parameter | Default | Maximum |
| ---------- | ------- | ------- |
| page\_size | 100 | 250 |
To paginate through results:
1. Make initial request (optionally with `page_size`)
2. If `pagination.has_more` is `true`, use `pagination.next_cursor` as the `cursor` parameter
3. Repeat until `has_more` is `false`
### Constraints
| Constraint | Value |
| --------------------------- | ---------------------------------------------------- |
| Maximum historical lookback | 2 years |
| Today and future dates | Not allowed (data available at \~02:00 UTC next day) |
| Timezone | All dates interpreted as UTC |
### Example Request (First Page)
```bash theme={null}
curl -X GET "https://api.augmentcode.com/analytics/v0/dau?date=2025-10-15&page_size=50" \
-H "Authorization: Bearer "
```
### Example Response
```json theme={null}
{
"users": [
{"user_email": "alice@example.com"},
{"user_email": "bob@example.com"},
{"service_account_name": "ci-bot"}
],
"pagination": {
"next_cursor": "eyJsYXN0X2lkIjoidXNlcjUwIn0=",
"has_more": true
},
"metadata": {
"effective_date": "2025-10-15",
"generated_at": "2025-10-16T10:30:00Z",
"returned_user_count": 3
}
}
```
### Example Request (Next Page)
```bash theme={null}
curl -X GET "https://api.augmentcode.com/analytics/v0/dau?date=2025-10-15&page_size=50&cursor=eyJsYXN0X2lkIjoidXNlcjUwIn0=" \
-H "Authorization: Bearer "
```
### Response Fields
| Field | Type | Description |
| ------------------------------- | ------- | -------------------------------------------------------- |
| users | array | Array of active users |
| users\[].user\_email | string | User's email address (for regular users) |
| users\[].service\_account\_name | string | Service account name (for service accounts) |
| pagination.next\_cursor | string | Cursor for fetching next page (empty if no more results) |
| pagination.has\_more | boolean | `true` if more results are available |
| metadata.effective\_date | string | Actual date used (UTC, after defaults) |
| metadata.generated\_at | string | Response generation timestamp (ISO 8601) |
| metadata.returned\_user\_count | integer | Number of users returned in this page |
Each user has either `user_email` or `service_account_name`, never both.
***
## GET /analytics/v0/daily-usage
Returns daily usage metrics for your organization over a date range. Days with no activity are omitted from the response.
### Query Parameters
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------- |
| start\_date | string | No | Start date in `YYYY-MM-DD` format (UTC) |
| end\_date | string | No | End date in `YYYY-MM-DD` format (UTC) |
### Date Range Behavior
| Scenario | Behavior |
| -------------------------- | -------------------------------------------------------------- |
| Neither date provided | Returns last 7 days ending at yesterday (UTC) |
| Only `start_date` provided | Returns 7 days starting from `start_date`, capped at yesterday |
| Only `end_date` provided | Returns 7 days ending at `end_date` |
| Both dates provided | Returns the specified inclusive range |
### Constraints
| Constraint | Value |
| --------------------------- | ---------------------------------------------------- |
| Maximum date range | 90 days |
| Maximum historical lookback | 2 years |
| Today and future dates | Not allowed (data available at \~02:00 UTC next day) |
| Timezone | All dates interpreted as UTC |
### Example Request
```bash theme={null}
curl -s -X GET "https://api.augmentcode.com/analytics/v0/daily-usage?start_date=2025-10-15&end_date=2025-10-20" \
-H "Authorization: Bearer " | jq .
```
### Example Response
```json theme={null}
{
"daily_usage": [
{
"date": "2025-10-15",
"metrics": {
"total_modified_lines_of_code": 1250,
"total_messages": 340,
"total_tool_calls": 890,
"completions_count": 1500,
"completions_accepted": 1120,
"completions_lines_of_code": 980,
"chat_messages": 85,
"remote_agent_messages": 0,
"remote_agent_lines_of_code": 0,
"ide_agent_messages": 150,
"ide_agent_lines_of_code": 95,
"cli_agent_interactive_messages": 40,
"cli_agent_interactive_lines_of_code": 35,
"cli_agent_non_interactive_messages": 20,
"cli_agent_non_interactive_lines_of_code": 20
}
}
],
"metadata": {
"effective_start_date": "2025-10-15",
"effective_end_date": "2025-10-20",
"generated_at": "2025-10-21T10:30:00Z",
"total_days": 1
}
}
```
### Response Fields
| Field | Type | Description |
| --------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| daily\_usage | array | Array of daily usage data points (days with no activity omitted) |
| daily\_usage\[].date | string | Calendar date (`YYYY-MM-DD`) |
| daily\_usage\[].metrics | object | Usage metrics for this date |
| daily\_usage\[].metrics.total\_modified\_lines\_of\_code | integer | Total lines of code modified across all interactions |
| daily\_usage\[].metrics.total\_messages | integer | Total messages across all interaction types |
| daily\_usage\[].metrics.total\_tool\_calls | integer | Total tool calls across all agent types |
| daily\_usage\[].metrics.completions\_count | integer | Number of completion requests |
| daily\_usage\[].metrics.completions\_accepted | integer | Number of completions accepted by users |
| daily\_usage\[].metrics.completions\_lines\_of\_code | integer | Lines of code from completions |
| daily\_usage\[].metrics.completions\_suggested\_lines\_of\_code | integer | Lines of code suggested by completions (before acceptance) |
| daily\_usage\[].metrics.chat\_messages | integer | Number of chat messages |
| daily\_usage\[].metrics.remote\_agent\_messages | integer | Number of Remote Agent messages. Remote Agent has been removed from IDE extensions; this field is retained for historical data. |
| daily\_usage\[].metrics.remote\_agent\_lines\_of\_code | integer | Lines of code from Remote Agent. Remote Agent has been removed from IDE extensions; this field is retained for historical data. |
| daily\_usage\[].metrics.ide\_agent\_messages | integer | Number of IDE Agent messages |
| daily\_usage\[].metrics.ide\_agent\_lines\_of\_code | integer | Lines of code from IDE Agent |
| daily\_usage\[].metrics.cli\_agent\_interactive\_messages | integer | Number of CLI Agent interactive messages |
| daily\_usage\[].metrics.cli\_agent\_interactive\_lines\_of\_code | integer | Lines of code from CLI Agent interactive mode |
| daily\_usage\[].metrics.cli\_agent\_non\_interactive\_messages | integer | Number of CLI Agent non-interactive messages |
| daily\_usage\[].metrics.cli\_agent\_non\_interactive\_lines\_of\_code | integer | Lines of code from CLI Agent non-interactive mode |
| metadata.effective\_start\_date | string | Actual start date used (UTC, after defaults/clamping) |
| metadata.effective\_end\_date | string | Actual end date used (UTC, after defaults/clamping) |
| metadata.generated\_at | string | Response generation timestamp (ISO 8601) |
| metadata.total\_days | integer | Number of days with data in the response |
***
## GET /analytics/v0/user-activity
Returns aggregated usage metrics per user over a date range. Users with no activity are omitted. Supports pagination.
### Query Parameters
| Parameter | Type | Required | Description |
| ----------- | ------- | -------- | ---------------------------------------- |
| start\_date | string | No | Start date in `YYYY-MM-DD` format (UTC) |
| end\_date | string | No | End date in `YYYY-MM-DD` format (UTC) |
| cursor | string | No | Pagination cursor from previous response |
| page\_size | integer | No | Number of results per page |
### Date Range Behavior
| Scenario | Behavior |
| -------------------------- | -------------------------------------------------------------- |
| Neither date provided | Returns last 7 days ending at yesterday (UTC) |
| Only `start_date` provided | Returns 7 days starting from `start_date`, capped at yesterday |
| Only `end_date` provided | Returns 7 days ending at `end_date` |
| Both dates provided | Returns the specified inclusive range |
### Pagination
| Parameter | Default | Maximum |
| ---------- | ------- | ------- |
| page\_size | 50 | 100 |
To paginate through results:
1. Make initial request (optionally with `page_size`)
2. If `pagination.has_more` is `true`, use `pagination.next_cursor` as the `cursor` parameter
3. Repeat until `has_more` is `false`
### Constraints
| Constraint | Value |
| --------------------------- | ---------------------------------------------------- |
| Maximum date range | 90 days |
| Maximum historical lookback | 2 years |
| Today and future dates | Not allowed (data available at \~02:00 UTC next day) |
| Timezone | All dates interpreted as UTC |
### Example Request
```bash theme={null}
curl -s -X GET "https://api.augmentcode.com/analytics/v0/user-activity?start_date=2025-10-15&end_date=2025-10-20&page_size=3" \
-H "Authorization: Bearer " | jq .
```
### Example Response
```json theme={null}
{
"users": [
{
"user_email": "alice@example.com",
"active_days": 5,
"metrics": {
"total_modified_lines_of_code": 450,
"total_messages": 65,
"total_tool_calls": 120,
"completions_count": 320,
"completions_accepted": 280,
"completions_lines_of_code": 350,
"chat_messages": 25,
"remote_agent_messages": 0,
"remote_agent_lines_of_code": 0,
"ide_agent_messages": 30,
"ide_agent_lines_of_code": 40,
"cli_agent_interactive_messages": 8,
"cli_agent_interactive_lines_of_code": 10,
"cli_agent_non_interactive_messages": 5,
"cli_agent_non_interactive_lines_of_code": 5
}
},
{
"user_email": "bob@example.com",
"active_days": 3,
"metrics": {
"total_modified_lines_of_code": 280,
"total_messages": 70,
"total_tool_calls": 75,
"completions_count": 150,
"completions_accepted": 120,
"completions_lines_of_code": 180,
"chat_messages": 40,
"remote_agent_messages": 0,
"remote_agent_lines_of_code": 0,
"ide_agent_messages": 20,
"ide_agent_lines_of_code": 55,
"cli_agent_interactive_messages": 3,
"cli_agent_interactive_lines_of_code": 15,
"cli_agent_non_interactive_messages": 2,
"cli_agent_non_interactive_lines_of_code": 5
}
},
{
"service_account_name": "ci-bot",
"active_days": 6,
"metrics": {
"total_modified_lines_of_code": 200,
"total_messages": 50,
"total_tool_calls": 85,
"completions_count": 0,
"completions_accepted": 0,
"completions_lines_of_code": 0,
"chat_messages": 0,
"remote_agent_messages": 0,
"remote_agent_lines_of_code": 0,
"ide_agent_messages": 0,
"ide_agent_lines_of_code": 0,
"cli_agent_interactive_messages": 0,
"cli_agent_interactive_lines_of_code": 0,
"cli_agent_non_interactive_messages": 50,
"cli_agent_non_interactive_lines_of_code": 200
}
}
],
"pagination": {
"next_cursor": "eyJsYXN0X2lkIjoidXNlcjMifQ==",
"has_more": true
},
"metadata": {
"effective_start_date": "2025-10-15",
"effective_end_date": "2025-10-20",
"generated_at": "2025-10-21T10:30:00Z",
"total_days": 6,
"returned_user_count": 3
}
}
```
### Response Fields
| Field | Type | Description |
| -------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| users | array | Array of user activity records (users with no activity omitted) |
| users\[].user\_email | string | User's email address (for regular users) |
| users\[].service\_account\_name | string | Service account name (for service accounts) |
| users\[].active\_days | integer | Number of distinct days with activity in the date range |
| users\[].metrics | object | Usage metrics for this user (summed over date range) |
| users\[].metrics.total\_modified\_lines\_of\_code | integer | Total lines of code modified across all interactions |
| users\[].metrics.total\_messages | integer | Total messages across all interaction types |
| users\[].metrics.total\_tool\_calls | integer | Total tool calls across all agent types |
| users\[].metrics.completions\_count | integer | Number of completion requests |
| users\[].metrics.completions\_accepted | integer | Number of completions accepted |
| users\[].metrics.completions\_lines\_of\_code | integer | Lines of code from completions |
| users\[].metrics.completions\_suggested\_lines\_of\_code | integer | Lines of code suggested by completions (before acceptance) |
| users\[].metrics.chat\_messages | integer | Number of chat messages |
| users\[].metrics.remote\_agent\_messages | integer | Number of Remote Agent messages. Remote Agent has been removed from IDE extensions; this field is retained for historical data. |
| users\[].metrics.remote\_agent\_lines\_of\_code | integer | Lines of code from Remote Agent. Remote Agent has been removed from IDE extensions; this field is retained for historical data. |
| users\[].metrics.ide\_agent\_messages | integer | Number of IDE Agent messages |
| users\[].metrics.ide\_agent\_lines\_of\_code | integer | Lines of code from IDE Agent |
| users\[].metrics.cli\_agent\_interactive\_messages | integer | Number of CLI Agent interactive messages |
| users\[].metrics.cli\_agent\_interactive\_lines\_of\_code | integer | Lines of code from CLI Agent interactive mode |
| users\[].metrics.cli\_agent\_non\_interactive\_messages | integer | Number of CLI Agent non-interactive messages |
| users\[].metrics.cli\_agent\_non\_interactive\_lines\_of\_code | integer | Lines of code from CLI Agent non-interactive mode |
| pagination.next\_cursor | string | Cursor for fetching next page (empty if no more results) |
| pagination.has\_more | boolean | `true` if more results are available |
| metadata.effective\_start\_date | string | Actual start date used (UTC, after defaults/clamping) |
| metadata.effective\_end\_date | string | Actual end date used (UTC, after defaults/clamping) |
| metadata.generated\_at | string | Response generation timestamp (ISO 8601) |
| metadata.total\_days | integer | Total number of days in the queried date range |
| metadata.returned\_user\_count | integer | Number of users returned in this page |
Each user has either `user_email` or `service_account_name`, never both.
***
## GET /analytics/v0/daily-user-activity-by-editor-language
Returns user activity metrics broken down by language and editor for a specific date. Supports pagination.
### Query Parameters
| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ------------------------------------------ |
| date | string | No | Date to query in `YYYY-MM-DD` format (UTC) |
| cursor | string | No | Pagination cursor from previous response |
| page\_size | integer | No | Number of results per page |
### Date Behavior
| Scenario | Behavior |
| ----------------- | ------------------------------------------------------------- |
| Date not provided | Defaults to yesterday (UTC) |
| Date provided | Returns activity for that date (must be yesterday or earlier) |
### Pagination
| Parameter | Default | Maximum |
| ---------- | ------- | ------- |
| page\_size | 50 | 100 |
To paginate through results:
1. Make initial request (optionally with `page_size`)
2. If `pagination.has_more` is `true`, use `pagination.next_cursor` as the `cursor` parameter
3. Repeat until `has_more` is `false`
### Constraints
| Constraint | Value |
| --------------------------- | ---------------------------------------------------- |
| Maximum historical lookback | 2 years |
| Today and future dates | Not allowed (data available at \~02:00 UTC next day) |
| Timezone | All dates interpreted as UTC |
### Example Request (First Page)
```bash theme={null}
curl -X GET "https://api.augmentcode.com/analytics/v0/daily-user-activity-by-editor-language?date=2025-10-15&page_size=50" \
-H "Authorization: Bearer "
```
### Example Response
```json theme={null}
{
"records": [
{
"user_email": "alice@example.com",
"language": "Python",
"editor": "VSCode",
"metrics": {
"total_modified_lines_of_code": 150,
"total_messages": 25,
"total_tool_calls": 40,
"completions_count": 80,
"completions_accepted": 65,
"completions_lines_of_code": 120,
"chat_messages": 10,
"remote_agent_messages": 0,
"remote_agent_lines_of_code": 0,
"ide_agent_messages": 8,
"ide_agent_lines_of_code": 12,
"cli_agent_interactive_messages": 2,
"cli_agent_interactive_lines_of_code": 3,
"cli_agent_non_interactive_messages": 0,
"cli_agent_non_interactive_lines_of_code": 0
}
},
{
"user_email": "alice@example.com",
"language": "TypeScript",
"editor": "VSCode",
"metrics": {
"total_modified_lines_of_code": 80,
"total_messages": 12,
"total_tool_calls": 18,
"completions_count": 45,
"completions_accepted": 38,
"completions_lines_of_code": 60,
"chat_messages": 5,
"remote_agent_messages": 0,
"remote_agent_lines_of_code": 0,
"ide_agent_messages": 4,
"ide_agent_lines_of_code": 10,
"cli_agent_interactive_messages": 1,
"cli_agent_interactive_lines_of_code": 2,
"cli_agent_non_interactive_messages": 0,
"cli_agent_non_interactive_lines_of_code": 0
}
}
],
"pagination": {
"next_cursor": "eyJsYXN0X2lkIjoidXNlcjMifQ==",
"has_more": true
},
"metadata": {
"effective_date": "2025-10-15",
"generated_at": "2025-10-16T10:30:00Z",
"returned_record_count": 2
}
}
```
### Example Request (Next Page)
```bash theme={null}
curl -X GET "https://api.augmentcode.com/analytics/v0/daily-user-activity-by-editor-language?date=2025-10-15&page_size=50&cursor=eyJsYXN0X2lkIjoidXNlcjMifQ==" \
-H "Authorization: Bearer "
```
### Response Fields
| Field | Type | Description |
| ---------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| records | array | Array of user/language/editor activity records |
| records\[].user\_email | string | User's email address (for regular users) |
| records\[].service\_account\_name | string | Service account name (for service accounts) |
| records\[].language | string | Programming language (e.g., "Python", "TypeScript", "Unknown") |
| records\[].editor | string | Editor/IDE name (e.g., "VSCode", "JetBrains", "CLI", "Unknown") |
| records\[].metrics | object | Usage metrics for this user/language/editor combination |
| records\[].metrics.total\_modified\_lines\_of\_code | integer | Total lines of code modified across all interactions |
| records\[].metrics.total\_messages | integer | Total messages across all interaction types |
| records\[].metrics.total\_tool\_calls | integer | Total tool calls across all agent types |
| records\[].metrics.completions\_count | integer | Number of completion requests |
| records\[].metrics.completions\_accepted | integer | Number of completions accepted |
| records\[].metrics.completions\_lines\_of\_code | integer | Lines of code from completions |
| records\[].metrics.completions\_suggested\_lines\_of\_code | integer | Lines of code suggested by completions (before acceptance) |
| records\[].metrics.chat\_messages | integer | Number of chat messages |
| records\[].metrics.remote\_agent\_messages | integer | Number of Remote Agent messages. Remote Agent has been removed from IDE extensions; this field is retained for historical data. |
| records\[].metrics.remote\_agent\_lines\_of\_code | integer | Lines of code from Remote Agent. Remote Agent has been removed from IDE extensions; this field is retained for historical data. |
| records\[].metrics.ide\_agent\_messages | integer | Number of IDE Agent messages |
| records\[].metrics.ide\_agent\_lines\_of\_code | integer | Lines of code from IDE Agent |
| records\[].metrics.cli\_agent\_interactive\_messages | integer | Number of CLI Agent interactive messages |
| records\[].metrics.cli\_agent\_interactive\_lines\_of\_code | integer | Lines of code from CLI Agent interactive mode |
| records\[].metrics.cli\_agent\_non\_interactive\_messages | integer | Number of CLI Agent non-interactive messages |
| records\[].metrics.cli\_agent\_non\_interactive\_lines\_of\_code | integer | Lines of code from CLI Agent non-interactive mode |
| pagination.next\_cursor | string | Cursor for fetching next page (empty if no more results) |
| pagination.has\_more | boolean | `true` if more results are available |
| metadata.effective\_date | string | Actual date used (UTC, after defaults) |
| metadata.generated\_at | string | Response generation timestamp (ISO 8601) |
| metadata.returned\_record\_count | integer | Number of records returned in this page |
Each record has either `user_email` or `service_account_name`, never both. A single user may have multiple records if they used different language/editor combinations on the queried date.
***
## GET /analytics/v0/credit-usage-by-user
Returns credit usage per user over a date range. Supports optional breakdowns by date and/or model. Supports pagination.
### Query Parameters
| Parameter | Type | Required | Description |
| ----------- | ------- | -------- | -------------------------------------------------- |
| start\_date | string | No | Start date in `YYYY-MM-DD` format (UTC) |
| end\_date | string | No | End date in `YYYY-MM-DD` format (UTC) |
| by\_date | boolean | No | When `true`, results include a per-date breakdown |
| by\_model | boolean | No | When `true`, results include a per-model breakdown |
| cursor | string | No | Pagination cursor from previous response |
| page\_size | integer | No | Number of results per page |
### Date Range Behavior
| Scenario | Behavior |
| -------------------------- | ---------------------------------------------------------------- |
| Neither date provided | Returns last 7 days ending at yesterday (UTC) |
| Only `start_date` provided | Returns 7 days starting from `start_date`, capped at today (UTC) |
| Only `end_date` provided | Returns 7 days ending at `end_date` |
| Both dates provided | Returns the specified inclusive range |
Unlike most Analytics API endpoints, this endpoint allows querying up to and including today's date. Credit usage data is updated approximately every 90 minutes and may be up to 90 minutes out of date.
### Dimensions
Use `by_date` and `by_model` to control how results are grouped:
| Dimensions | Result |
| --------------- | ------------------------------------------------------- |
| Neither set | One row per user with total credits over the date range |
| `by_date=true` | One row per user per date |
| `by_model=true` | One row per user per model |
| Both `true` | One row per user per date per model |
When a dimension is not requested, the corresponding field (`date` or `model_name`) is omitted from the response records.
### Pagination
| Parameter | Default | Maximum |
| ---------- | ------- | ------- |
| page\_size | 100 | 500 |
To paginate through results:
1. Make initial request (optionally with `page_size`)
2. If `pagination.has_more` is `true`, use `pagination.next_cursor` as the `cursor` parameter
3. Repeat until `has_more` is `false`
### Constraints
| Constraint | Value |
| ------------------ | ---------------------------- |
| Maximum date range | 90 days |
| End date | Must be ≤ today (UTC) |
| Timezone | All dates interpreted as UTC |
### Example Request (No Dimensions)
```bash theme={null}
curl -X GET "https://api.augmentcode.com/analytics/v0/credit-usage-by-user" \
-H "Authorization: Bearer "
```
### Example Response
```json theme={null}
{
"records": [
{ "user_email": "alice@acme.com", "credits_consumed": 4200 },
{ "user_email": "bob@acme.com", "credits_consumed": 1850 },
{ "service_account_name": "ci-bot", "credits_consumed": 920 }
],
"pagination": {
"has_more": false
},
"metadata": {
"effective_start_date": "2026-03-10",
"effective_end_date": "2026-03-16",
"generated_at": "2026-03-17T04:00:00Z",
"returned_record_count": 3
}
}
```
### Example Request (First Page, With Dimensions)
```bash theme={null}
curl -X GET "https://api.augmentcode.com/analytics/v0/credit-usage-by-user?start_date=2026-03-01&end_date=2026-03-07&by_date=true&by_model=true&page_size=2" \
-H "Authorization: Bearer "
```
### Example Response
```json theme={null}
{
"records": [
{
"user_email": "alice@acme.com",
"credits_consumed": 350,
"date": "2026-03-01",
"model_name": "claude-sonnet"
},
{
"user_email": "alice@acme.com",
"credits_consumed": 120,
"date": "2026-03-01",
"model_name": "gpt-4o"
}
],
"pagination": {
"next_cursor": "eyJ1IjoiMDAwMSIsImQiOiIyMDI2LTAzLTAxIiwibSI6ImdwdC00byJ9",
"has_more": true
},
"metadata": {
"effective_start_date": "2026-03-01",
"effective_end_date": "2026-03-07",
"generated_at": "2026-03-17T04:00:00Z",
"returned_record_count": 2
}
}
```
### Example Request (Next Page)
```bash theme={null}
curl -X GET "https://api.augmentcode.com/analytics/v0/credit-usage-by-user?start_date=2026-03-01&end_date=2026-03-07&by_date=true&by_model=true&page_size=2&cursor=eyJ1IjoiMDAwMSIsImQiOiIyMDI2LTAzLTAxIiwibSI6ImdwdC00byJ9" \
-H "Authorization: Bearer "
```
### Response Fields
| Field | Type | Description |
| --------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| records | array | Array of credit usage records |
| records\[].user\_email | string | User's email address (for regular users) |
| records\[].service\_account\_name | string | Service account name (for service accounts) |
| records\[].credits\_consumed | integer | Number of credits consumed |
| records\[].date | string | Calendar date (`YYYY-MM-DD`). Present only when `by_date=true`. |
| records\[].model\_name | string | Model name (e.g., `"claude-sonnet"`, `"gpt-4o"`). Present only when `by_model=true`. |
| pagination.next\_cursor | string | Cursor for fetching next page (empty if no more results) |
| pagination.has\_more | boolean | `true` if more results are available |
| metadata.effective\_start\_date | string | Actual start date used (UTC, after defaults/clamping) |
| metadata.effective\_end\_date | string | Actual end date used (UTC, after defaults/clamping) |
| metadata.generated\_at | string | Response generation timestamp (ISO 8601) |
| metadata.returned\_record\_count | integer | Number of records returned in this page |
Each record has either `user_email` or `service_account_name`, never both.
***
## POST /analytics/v0/cost-analytics
Returns cost and token usage analytics for your organization over a date range, with configurable group-by dimensions and time granularity. Supports pagination.
Unlike the metrics endpoints above, this endpoint accepts a JSON request body (`POST`). Dates are `YYYY-MM-DD` strings in both requests and responses, and enum values are sent and returned as their string names.
### Request Body (JSON)
| Field | Type | Required | Description |
| ------------------------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start\_date | string | No | Inclusive start date as a `"YYYY-MM-DD"` string (UTC). If omitted, the date range defaults to the last 7 days ending at yesterday (UTC). When either date is provided, **both** `start_date` and `end_date` are required. A non-string value is rejected (`start_date must be a string in YYYY-MM-DD format`). |
| end\_date | string | No | Inclusive end date as a `"YYYY-MM-DD"` string (UTC). See `start_date` for the defaulting and both-dates-required rules. |
| group\_by\_keys | array of strings | No | Dimensions to group results by. Multiple keys can be combined for multi-dimensional breakdowns. Empty means a single aggregate total. See [Group-By Dimensions](#group-by-dimensions). |
| granularity | string | No | Time granularity. One of `COST_ANALYTICS_TIME_GRANULARITY_TOTAL` (default) or `COST_ANALYTICS_TIME_GRANULARITY_DAY`. |
| filters | object | No | Optional filters to narrow results. When unset, no filtering is applied. |
| filters.user\_emails | array of strings | No | Only include usage from these users (case-insensitive). |
| filters.service\_account\_names | array of strings | No | Only include usage from these service accounts (case-sensitive). Combined with `user_emails` as a union. |
| filters.product\_names | array of strings | No | Only include usage from these products (e.g. `"Cosmos"`, `"IDE"`). |
| filters.resource\_names | array of strings | No | Only include usage from these resources (e.g. an LLM model name). |
| filters.expert\_ids | array of strings | No | Only include usage from these experts. |
| cursor | string | No | Opaque pagination cursor from a previous response. Omit or leave empty for the first page. |
| page\_size | integer | No | Number of data points per page. Default 100, maximum 1000. |
Only the fields listed above are accepted. Any other top-level field is rejected with a 400 (`invalid query parameters: `).
### Group-By Dimensions
`group_by_keys` controls how results are grouped. Each requested dimension populates the corresponding field in `data_points[].group_by_values`:
| Group-by key | Populates | Description |
| ---------------------------------- | ---------------------------------------- | -------------------------------------------------------------------- |
| `COST_ANALYTICS_GROUP_BY_PRODUCT` | `product_display_name` | Group by product (e.g. `"Cosmos"`, `"IDE"`, `"CLI"`) |
| `COST_ANALYTICS_GROUP_BY_RESOURCE` | `resource_display_name`, `resource_type` | Group by resource (an LLM model or compute VM) |
| `COST_ANALYTICS_GROUP_BY_USER` | `user_info` | Group by user. **Includes PII** (user email or service account name) |
| `COST_ANALYTICS_GROUP_BY_EXPERT` | `expert_info` | Group by expert (agent persona) |
Requesting `COST_ANALYTICS_GROUP_BY_USER` returns per-user identifying information (email or service account name) in the response. Ensure your use of this dimension complies with your organization's data-handling policies.
### Date Range Behavior
| Scenario | Behavior |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Both `start_date` and `end_date` omitted | Returns last 7 days ending at yesterday (UTC) |
| Only one of `start_date` / `end_date` provided | Rejected with `InvalidArgument` (`date_filters must include both start_date and end_date`) |
| Both dates provided | Returns the specified inclusive range |
### Pagination
| Parameter | Default | Maximum |
| ---------- | ------- | ------- |
| page\_size | 100 | 1000 |
To paginate through results:
1. Make initial request (optionally with `page_size`)
2. If `pagination.has_more` is `true`, use `pagination.next_cursor` as the `cursor` parameter
3. Repeat until `has_more` is `false`
### Constraints
| Constraint | Value |
| --------------------------- | ---------------------------- |
| Maximum date range | 90 days |
| Maximum historical lookback | 2 years |
| Maximum page size | 1000 |
| Timezone | All dates interpreted as UTC |
### Example Request
```bash theme={null}
curl -X POST "https://api.augmentcode.com/analytics/v0/cost-analytics" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"start_date": "2025-10-15",
"end_date": "2025-10-21",
"group_by_keys": ["COST_ANALYTICS_GROUP_BY_PRODUCT"],
"granularity": "COST_ANALYTICS_TIME_GRANULARITY_TOTAL"
}'
```
### Example Response
```json theme={null}
{
"data_points": [
{
"start_date": "2025-10-15",
"end_date": "2025-10-21",
"cost_metrics": {
"billed_amount_usd": "1234.56",
"estimated_customer_cost_usd": "1234.56",
"base_cost_usd": "987.65",
"surcharge_usd": "246.91",
"input_tokens": 15000000,
"output_tokens": 3200000,
"cache_read_tokens": 8000000,
"cache_write_tokens": 1200000,
"credits_consumed": "61728"
},
"group_by_values": {
"product_display_name": "Cosmos"
}
},
{
"start_date": "2025-10-15",
"end_date": "2025-10-21",
"cost_metrics": {
"billed_amount_usd": "456.78",
"estimated_customer_cost_usd": "456.78",
"base_cost_usd": "365.42",
"surcharge_usd": "91.36",
"input_tokens": 6000000,
"output_tokens": 1100000,
"cache_read_tokens": 3000000,
"cache_write_tokens": 500000,
"credits_consumed": "22839"
},
"group_by_values": {
"product_display_name": "IDE"
}
}
],
"pagination": {
"next_cursor": "",
"has_more": false
},
"metadata": {
"effective_start_date": "2025-10-15",
"effective_end_date": "2025-10-21",
"generated_at": "2025-10-22T10:30:00Z",
"returned_data_point_count": 2
}
}
```
### Example Data Point (grouped by USER and RESOURCE)
When `group_by_keys` includes multiple dimensions, each data point's `group_by_values` is populated for every requested dimension:
```json theme={null}
{
"start_date": "2025-10-15",
"end_date": "2025-10-21",
"cost_metrics": {
"billed_amount_usd": "42.10",
"estimated_customer_cost_usd": "42.10",
"base_cost_usd": "33.68",
"surcharge_usd": "8.42",
"input_tokens": 520000,
"output_tokens": 98000,
"cache_read_tokens": 210000,
"cache_write_tokens": 40000,
"credits_consumed": "2105"
},
"group_by_values": {
"resource_display_name": "Claude Sonnet 4",
"resource_type": "COST_ANALYTICS_RESOURCE_TYPE_MODEL",
"user_info": {
"user_type": "COST_ANALYTICS_USER_TYPE_USER",
"user_email": "alice@example.com"
}
}
}
```
### Response Fields
| Field | Type | Description |
| ------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data\_points | array | Usage analytics data points matching the query. Ordered for stable cursor-based pagination. |
| data\_points\[].start\_date | string | Inclusive start date of the time range this data point covers, as a `"YYYY-MM-DD"` string. |
| data\_points\[].end\_date | string | Inclusive end date of the time range this data point covers, as a `"YYYY-MM-DD"` string. |
| data\_points\[].cost\_metrics | object | Cost and token metrics for this data point. |
| data\_points\[].cost\_metrics.billed\_amount\_usd | string | Billed amount in USD (decimal string). What the customer is billed. |
| data\_points\[].cost\_metrics.estimated\_customer\_cost\_usd | string | Estimated customer cost in USD (decimal string). For BYOK on enterprise this includes base cost plus surcharge; for self-serve it equals `billed_amount_usd`. |
| data\_points\[].cost\_metrics.base\_cost\_usd | string | Base cost in USD (decimal string). Augment's cost to serve the request. |
| data\_points\[].cost\_metrics.surcharge\_usd | string | Surcharge in USD (decimal string). For non-BYOK: `billed_amount_usd - base_cost_usd`. For BYOK: the full `billed_amount_usd`. |
| data\_points\[].cost\_metrics.input\_tokens | integer | Total input tokens (JSON number; returned as a string only when greater than 2^53−1). |
| data\_points\[].cost\_metrics.output\_tokens | integer | Total output tokens (JSON number; returned as a string only when greater than 2^53−1). |
| data\_points\[].cost\_metrics.cache\_read\_tokens | integer | Total cache read tokens (JSON number; returned as a string only when greater than 2^53−1). |
| data\_points\[].cost\_metrics.cache\_write\_tokens | integer | Total cache write tokens (JSON number; returned as a string only when greater than 2^53−1). |
| data\_points\[].cost\_metrics.credits\_consumed | string | Total credits consumed (decimal string). |
| data\_points\[].group\_by\_values | object | Group-by key values for this data point. Fields are populated based on the requested `group_by_keys`. |
| data\_points\[].group\_by\_values.product\_display\_name | string | Product name. Present when grouping by `COST_ANALYTICS_GROUP_BY_PRODUCT`. |
| data\_points\[].group\_by\_values.resource\_display\_name | string | Resource name (LLM model or compute VM). Present when grouping by `COST_ANALYTICS_GROUP_BY_RESOURCE`. |
| data\_points\[].group\_by\_values.resource\_type | string | `COST_ANALYTICS_RESOURCE_TYPE_MODEL` or `COST_ANALYTICS_RESOURCE_TYPE_COMPUTE`. Present when grouping by `COST_ANALYTICS_GROUP_BY_RESOURCE`. |
| data\_points\[].group\_by\_values.user\_info | object | User information. Present when grouping by `COST_ANALYTICS_GROUP_BY_USER`. |
| data\_points\[].group\_by\_values.user\_info.user\_type | string | `COST_ANALYTICS_USER_TYPE_USER`, `COST_ANALYTICS_USER_TYPE_SERVICE_ACCOUNT`, or `COST_ANALYTICS_USER_TYPE_BOT`. |
| data\_points\[].group\_by\_values.user\_info.user\_email | string | User's email address (for regular users). |
| data\_points\[].group\_by\_values.user\_info.service\_account\_name | string | Service account name (for service accounts). |
| data\_points\[].group\_by\_values.user\_info.bot\_name | string | Bot display name (for bot/automated accounts). |
| data\_points\[].group\_by\_values.expert\_info | object | Expert information. Present when grouping by `COST_ANALYTICS_GROUP_BY_EXPERT`. |
| data\_points\[].group\_by\_values.expert\_info.expert\_id | string | The expert ID. |
| data\_points\[].group\_by\_values.expert\_info.name | string | The expert's display name. |
| pagination.next\_cursor | string | Cursor for fetching next page (empty if no more results). |
| pagination.has\_more | boolean | `true` if more results are available. |
| metadata.effective\_start\_date | string | Actual start date used, as a `"YYYY-MM-DD"` string (UTC, after defaults/clamping). |
| metadata.effective\_end\_date | string | Actual end date used, as a `"YYYY-MM-DD"` string (UTC, after defaults/clamping). |
| metadata.generated\_at | string | Response generation timestamp (ISO 8601). |
| metadata.returned\_data\_point\_count | integer | Number of data points returned in this page. |
Within `user_info`, at most one of `user_email`, `service_account_name`, or `bot_name` is set; it may be unset for deleted or unresolvable accounts.
***
## POST /analytics/v0/get-user-budget-overrides
Returns per-user budget overrides configured for the organization. Budget overrides are custom limits for individual users or service accounts that differ from the organization's default per-user budget. Overrides for users no longer in the organization are silently omitted.
### Request Body (JSON)
| Field | Type | Required | Description |
| ----------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| user\_emails | array of strings | No | Email addresses to filter by (case-insensitive). If omitted (along with `service_account_names`), returns all overrides. |
| service\_account\_names | array of strings | No | Service account names to filter by. Can be combined with `user_emails`. |
| resource | string | No | Filter by resource type: `BUDGET_RESOURCE_CREDITS_CONSUMED` or `BUDGET_RESOURCE_USD_COST`. If omitted, returns all resource types. |
| period | string | No | Filter by period: `BUDGET_PERIOD_MONTHLY`. If omitted, returns all periods. |
### Constraints
| Constraint | Value |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Resource-plan compatibility | Returned overrides are filtered to match the organization's billing plan (credit-based or USD) |
| Identity | Each override has either `user_email` or `service_account_name`, never both |
| Unknown identities | Returns `InvalidArgument` listing all unknown emails or service account names (e.g., `user_email(s) not found on this organization: a@x.com, b@x.com`) |
### Example Request
```bash theme={null}
curl -X POST "https://api.augmentcode.com/analytics/v0/get-user-budget-overrides" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"user_emails": ["alice@example.com", "bob@example.com"],
"resource": "BUDGET_RESOURCE_CREDITS_CONSUMED",
"period": "BUDGET_PERIOD_MONTHLY"
}'
```
### Example Response
```json theme={null}
{
"overrides": [
{
"user_email": "alice@example.com",
"resource": "BUDGET_RESOURCE_CREDITS_CONSUMED",
"period": "BUDGET_PERIOD_MONTHLY",
"config": {
"limit": "5000"
}
},
{
"user_email": "bob@example.com",
"resource": "BUDGET_RESOURCE_CREDITS_CONSUMED",
"period": "BUDGET_PERIOD_MONTHLY",
"config": {
"limit": "10000"
}
}
]
}
```
### Response Fields
| Field | Type | Description |
| ----------------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| overrides | array | Per-user budget overrides matching the request filters |
| overrides\[].user\_email | string | User's email address (regular users) |
| overrides\[].service\_account\_name | string | Service account name (service accounts) |
| overrides\[].resource | string | `BUDGET_RESOURCE_CREDITS_CONSUMED` or `BUDGET_RESOURCE_USD_COST` |
| overrides\[].period | string | `BUDGET_PERIOD_MONTHLY` |
| overrides\[].config.limit | string | Budget limit as a string-encoded positive integer. Empty string means the limit has been cleared. |
***
## POST /analytics/v0/set-user-budget-overrides
Sets per-user budget overrides for the organization in a single batch. To clear an override, set `config.limit` to an empty string.
Uses **partial-failure semantics**: valid overrides are applied even if some entries in the batch fail. Failed entries are returned in the `failures` array.
### Request Body (JSON)
| Field | Type | Required | Description |
| ----------------------------------- | ------ | ----------- | ---------------------------------------------------------------------------------------- |
| overrides | array | Yes | List of overrides to set. Must not be empty. |
| overrides\[].user\_email | string | Conditional | User's email address. Exactly one of `user_email` or `service_account_name` must be set. |
| overrides\[].service\_account\_name | string | Conditional | Service account name. Exactly one of `user_email` or `service_account_name` must be set. |
| overrides\[].resource | string | Yes | `BUDGET_RESOURCE_CREDITS_CONSUMED` or `BUDGET_RESOURCE_USD_COST`. |
| overrides\[].period | string | Yes | `BUDGET_PERIOD_MONTHLY`. |
| overrides\[].config | object | Yes | Budget configuration. |
| overrides\[].config.limit | string | Yes | Positive integer (max 18 digits, no leading zeros), or empty string `""` to clear. |
### Constraints
| Constraint | Value |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Maximum overrides per request | 5,000 |
| Identity | Exactly one of `user_email` or `service_account_name` per override |
| Duplicates | No duplicate (identity, resource, period) combinations in the same request |
| Resource-plan compatibility | Resource type must match the organization's billing plan (e.g., `BUDGET_RESOURCE_CREDITS_CONSUMED` on credit-based plans, `BUDGET_RESOURCE_USD_COST` on USD plans) |
| Limit format | Positive integer with no leading zeros, max 18 digits, or empty string to clear |
### Example Request
```bash theme={null}
curl -X POST "https://api.augmentcode.com/analytics/v0/set-user-budget-overrides" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"overrides": [
{
"user_email": "alice@example.com",
"resource": "BUDGET_RESOURCE_USD_COST",
"period": "BUDGET_PERIOD_MONTHLY",
"config": {"limit": "500"}
},
{
"service_account_name": "ci-bot",
"resource": "BUDGET_RESOURCE_USD_COST",
"period": "BUDGET_PERIOD_MONTHLY",
"config": {"limit": "200"}
}
]
}'
```
### Example Response (All Succeeded)
```json theme={null}
{
"failures": []
}
```
### Example Response (Partial Failure)
```json theme={null}
{
"failures": [
{
"user_email": "unknown@example.com",
"error_message": "user_email \"unknown@example.com\" does not correspond to a user on this organization"
}
]
}
```
Valid overrides in the batch were still applied. Only entries in `failures` were not.
### Response Fields
| Field | Type | Description |
| ---------------------------------- | ------ | -------------------------------------------------------------------- |
| failures | array | Per-override failures. Empty array means all overrides were applied. |
| failures\[].user\_email | string | Email of the user whose override failed (regular users) |
| failures\[].service\_account\_name | string | Service account name whose override failed (service accounts) |
| failures\[].error\_message | string | Human-readable description of the failure |
***
## Rate Limiting
The Analytics API enforces rate limits to ensure fair usage and system stability.
| Endpoint | Sustained rate | Burst allowance |
| ------------------------------------ | ---------------------------------------- | --------------- |
| Most endpoints | 60 requests/minute (1 request/second) | 20 requests |
| `/analytics/v0/credit-usage-by-user` | 30 requests/minute (0.5 requests/second) | 10 requests |
| `/analytics/v0/cost-analytics` | 30 requests/minute (0.5 requests/second) | 10 requests |
When you exceed the rate limit, the API returns HTTP status code `429 Too Many Requests`. Subsequent requests are blocked for approximately 10 seconds before new requests are accepted.
### Best Practices
1. **Batch your requests**: Instead of making many small requests, use larger date ranges (up to 90 days) to retrieve more data per request.
2. **Implement exponential backoff**: If you receive a `429` response, wait before retrying. Start with a short delay and increase it with each consecutive failure.
3. **Cache responses**: Most Analytics endpoints update only once daily, so cache responses and avoid re-fetching the same data within a 24-hour period. For `/analytics/v0/credit-usage-by-user`, which refreshes approximately every 90 minutes, use a shorter cache window of around 90 minutes. Budget override responses reflect real-time configuration and should not be cached long-term.
4. **Use pagination efficiently**: When paginating through large result sets, process each page before requesting the next one rather than fetching all pages as fast as possible.
5. **Spread requests over time**: If you need to make multiple API calls, distribute them evenly rather than sending them all at once.
***
## Error Responses
The API returns standard HTTP status codes:
| Status Code | Description |
| ----------- | ------------------------------------------------------------------ |
| 400 | Invalid request (e.g., invalid date format, range exceeds 90 days) |
| 401 | Missing or invalid authentication token |
| 403 | Insufficient permissions |
| 429 | Too many requests (rate limit exceeded) |
| 500 | Internal server error |
### Example Error Response
```json theme={null}
{
"error": {
"code": "InvalidArgument",
"message": "end_date cannot be later than yesterday (UTC)"
}
}
```