Analytics API Reference

Preview FeatureThe Analytics API is currently in preview and is available exclusively to Enterprise customers.

Important: Timezone and Data AvailabilityAll 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 FreshnessAnalytics 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

curl -X GET "https://api.augmentcode.com/analytics/v0/dau-count?start_date=2025-10-15&end_date=2025-10-20" \
  -H "Authorization: Bearer <your-api-token>"

Example Response

{
  "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:

Make initial request (optionally with page_size)
If pagination.has_more is true, use pagination.next_cursor as the cursor parameter
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)

curl -X GET "https://api.augmentcode.com/analytics/v0/dau?date=2025-10-15&page_size=50" \
  -H "Authorization: Bearer <your-api-token>"

Example Response

{
  "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)

curl -X GET "https://api.augmentcode.com/analytics/v0/dau?date=2025-10-15&page_size=50&cursor=eyJsYXN0X2lkIjoidXNlcjUwIn0=" \
  -H "Authorization: Bearer <your-api-token>"

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

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 <your-api-token>" | jq .

Example Response

{
  "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:

Make initial request (optionally with page_size)
If pagination.has_more is true, use pagination.next_cursor as the cursor parameter
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

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 <your-api-token>" | jq .

Example Response

{
  "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:

Make initial request (optionally with page_size)
If pagination.has_more is true, use pagination.next_cursor as the cursor parameter
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)

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 <your-api-token>"

Example Response

{
  "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)

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 <your-api-token>"

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:

Make initial request (optionally with page_size)
If pagination.has_more is true, use pagination.next_cursor as the cursor parameter
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)

curl -X GET "https://api.augmentcode.com/analytics/v0/credit-usage-by-user" \
  -H "Authorization: Bearer <your-api-token>"

Example Response

{
  "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)

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 <your-api-token>"

Example Response

{
  "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)

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 <your-api-token>"

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.
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: <field>).

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)
`COST_ANALYTICS_GROUP_BY_USER`	`user_info`	Group by user. Includes PII (user email or service account name)
`COST_ANALYTICS_GROUP_BY_BYOK_STATUS`	`byok_status`	Group by customer-provided API key usage (`COST_ANALYTICS_BYOK_STATUS_BYOK`) vs Augment-provided model usage (`COST_ANALYTICS_BYOK_STATUS_NON_BYOK`)
`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:

Make initial request (optionally with page_size)
If pagination.has_more is true, use pagination.next_cursor as the cursor parameter
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

curl -X POST "https://api.augmentcode.com/analytics/v0/cost-analytics" \
  -H "Authorization: Bearer <your-api-token>" \
  -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

{
  "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:

{
  "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.byok_status	string	`COST_ANALYTICS_BYOK_STATUS_BYOK` for customer-provided API key usage or `COST_ANALYTICS_BYOK_STATUS_NON_BYOK` for Augment-provided model usage. Present when grouping by `COST_ANALYTICS_GROUP_BY_BYOK_STATUS`.
data_points[].group_by_values.resource_display_name	string	Resource name (LLM model or compute). 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

curl -X POST "https://api.augmentcode.com/analytics/v0/get-user-budget-overrides" \
  -H "Authorization: Bearer <your-api-token>" \
  -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

{
  "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

curl -X POST "https://api.augmentcode.com/analytics/v0/set-user-budget-overrides" \
  -H "Authorization: Bearer <your-api-token>" \
  -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)

{
  "failures": []
}

Example Response (Partial Failure)

{
  "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

Batch your requests: Instead of making many small requests, use larger date ranges (up to 90 days) to retrieve more data per request.
Implement exponential backoff: If you receive a 429 response, wait before retrying. Start with a short delay and increase it with each consecutive failure.
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.
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.
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

{
  "error": {
    "code": "InvalidArgument",
    "message": "end_date cannot be later than yesterday (UTC)"
  }
}

​GET /analytics/v0/dau-count

​Query Parameters

​Date Range Behavior

​Constraints

​Example Request

​Example Response

​Response Fields

​GET /analytics/v0/dau

​Query Parameters

​Date Behavior

​Pagination

​Constraints

​Example Request (First Page)

​Example Response

​Example Request (Next Page)

​Response Fields

​GET /analytics/v0/daily-usage

​Query Parameters

​Date Range Behavior

​Constraints

​Example Request

​Example Response

​Response Fields

​GET /analytics/v0/user-activity

​Query Parameters

​Date Range Behavior

​Pagination

​Constraints

​Example Request

​Example Response

​Response Fields

​GET /analytics/v0/daily-user-activity-by-editor-language

​Query Parameters

​Date Behavior

​Pagination

​Constraints

​Example Request (First Page)

​Example Response

​Example Request (Next Page)

​Response Fields

​GET /analytics/v0/credit-usage-by-user

​Query Parameters

​Date Range Behavior

​Dimensions

​Pagination

​Constraints

​Example Request (No Dimensions)

​Example Response

​Example Request (First Page, With Dimensions)

​Example Response

​Example Request (Next Page)

​Response Fields

​POST /analytics/v0/cost-analytics

​Request Body (JSON)

​Group-By Dimensions

​Date Range Behavior

​Pagination

​Constraints

​Example Request

​Example Response

​Example Data Point (grouped by USER and RESOURCE)

​Response Fields

​POST /analytics/v0/get-user-budget-overrides

​Request Body (JSON)

​Constraints

​Example Request

​Example Response

​Response Fields

​POST /analytics/v0/set-user-budget-overrides

​Request Body (JSON)

​Constraints

​Example Request

​Example Response (All Succeeded)

​Example Response (Partial Failure)

​Response Fields

​Rate Limiting

​Best Practices

​Error Responses

​Example Error Response

GET /analytics/v0/dau-count

Query Parameters

Date Range Behavior

Constraints

Example Request

Example Response

Response Fields

GET /analytics/v0/dau

Query Parameters

Date Behavior

Pagination

Constraints

Example Request (First Page)

Example Response

Example Request (Next Page)

Response Fields

GET /analytics/v0/daily-usage

Query Parameters

Date Range Behavior

Constraints

Example Request

Example Response

Response Fields

GET /analytics/v0/user-activity

Query Parameters

Date Range Behavior

Pagination

Constraints

Example Request

Example Response

Response Fields

GET /analytics/v0/daily-user-activity-by-editor-language

Query Parameters

Date Behavior

Pagination

Constraints

Example Request (First Page)

Example Response

Example Request (Next Page)

Response Fields

GET /analytics/v0/credit-usage-by-user

Query Parameters

Date Range Behavior

Dimensions

Pagination

Constraints

Example Request (No Dimensions)

Example Response

Example Request (First Page, With Dimensions)

Example Response

Example Request (Next Page)

Response Fields

POST /analytics/v0/cost-analytics

Request Body (JSON)

Group-By Dimensions

Date Range Behavior

Pagination

Constraints

Example Request

Example Response

Example Data Point (grouped by USER and RESOURCE)

Response Fields

POST /analytics/v0/get-user-budget-overrides

Request Body (JSON)

Constraints

Example Request

Example Response

Response Fields

POST /analytics/v0/set-user-budget-overrides

Request Body (JSON)

Constraints

Example Request

Example Response (All Succeeded)

Example Response (Partial Failure)

Response Fields

Rate Limiting

Best Practices

Error Responses

Example Error Response