Access Builder's code generation Metrics API for programmatic access to Fusion Space usage metrics.
- Generate a Private Key on your Space's Settings page to gain access to metrics data.
- Request Organization-level or Space-level metrics programmatically.
Use Private Keys when you want to create a server-side only key for writing to your Builder account or to pull content that you want to keep private.
To view or use Private API Keys, you must have Admin permissions.
Tip: Keep your Private API Key secret. It allows anyone to have write access to your content in Builder. Only use it in API calls from your server, not calls from public client applications.
To manage the Private Keys for your Space:
- Go to your Space Settings.
- To the right of Private Keys, click the Edit button.
- Create or revoke as many keys as you need.
For more information on how to use Private Keys with models, visit Create a Private Model.
In rare situations, you may need to create a Private Key for your Organization. Follow the same process, but on your Organization's Settings page. For more details on this page, visit Manage your Organization.
Metrics include summarized details about your Organization or Space. This data can be used to obtain a general overview of what has happened over a period of time.
Retrieves usage data for an entire Organization.
Include your Organization's Private Key within the Authorization header. Augment your request with the following query parameters:
| Parameter | Required? | Description |
|---|---|---|
startDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
endDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
granularity | No | Value must be one of |
A sample response is included below:
{
"data": [
{
"period": "2025-07-01",
"metrics": {
"linesAdded": 0,
"linesRemoved": 0,
"totalLines": 1221754,
"linesAccepted": 641,
"events": 8039,
"users": 2,
"userPrompts": 233,
"designExports": 0,
"spaces": [
{
"spaceId": "your-space-id",
"spaceName": "Your Space Name",
"linesAdded": 0,
"linesRemoved": 0,
"totalLines": 1106096,
"linesAccepted": 0
},
...
]
}
}
],
"summary": {
"totalLinesGenerated": 1221754,
"totalLinesAccepted": 641,
"users": 2,
"totalUserPrompts": 233,
"totalDesignExports": 0
}
}For more details on the keys provided within the response, visit the following sections within this doc:
Retrieves usage data for a specific Space.
Include your Space's Private Key within the Authorization header. Augment your request with the following query parameters:
| Parameter | Required? | Description |
|---|---|---|
startDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
endDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
granularity | No | Value must be one of |
A sample response is included below:
{
"data": [
{
"period": "2025-07-01",
"metrics": {
"linesAdded": 0,
"linesRemoved": 0,
"linesAccepted": 0,
"totalLines": 1106096,
"events": 3825,
"users": 2,
"designExports": 0,
"userPrompts": 233,
"tokens": {
"total": 336275030,
"input": 2716702,
"output": 1359459,
"cacheWrite": 24997783,
"cacheInput": 307201086
}
}
}
],
"summary": {
"totalLinesGenerated": 1106096,
"totalLinesAccepted": 0,
"totalUsers": 2,
"totalUserPrompts": 233,
"totalDesignExports": 0,
}
}For more details on the keys provided within the response, visit the following sections within this doc:
Retrieves usage data for an Organization by user.
Include your Organization's Private Key within the Authorization header. Augment your request with the following query parameters:
| Parameter | Required? | Description |
|---|---|---|
startDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
endDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
userId | No | Filter by specific user ID. |
projectId | No | Filter by specific Project ID. |
sortBy | No | Sorts the user list. Value must be one of |
sortOrder | No | Orders a sorted list. Value must be one of |
A sample response is included below:
{
"data": [
{
"userId": "user123",
"userEmail": "user@example.com",
"lastActive": "2024-01-15T14:30:00Z",
"designExports": 5,
"metrics": {
"linesAdded": 1250,
"linesRemoved": 320,
"linesAccepted": 980,
"totalLines": 1570,
"events": 45,
"userPrompts": 28,
"creditsUsed": 12.5,
"prsMerged": 3,
"tokens": {
"total": 125000,
"input": 45000,
"output": 80000,
"cacheWrite": 15000,
"cacheInput": 5000
}
}
},
// ...
]
}For more details on the keys provided within the response, visit the following sections within this doc:
Retrieves usage data for a specific Space by user.
Include your Space's Private Key within the Authorization header. Augment your request with the following query parameters:
| Parameter | Required? | Description |
|---|---|---|
startDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
endDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
sortBy | No | Sorts the user list. Value must be one of |
sortOrder | No | Orders a sorted list. Value must be one of |
A sample response is included below:
{
"data": [
{
"userId": "USER_ID",
"lastActive": "2025-07-29T21:32:36.650Z",
"metrics": {
"linesAdded": 0,
"linesRemoved": 0,
"linesAccepted": 0,
"totalLines": 162829,
"events": 991,
"userPrompts": 218,
"creditsUsed": "210",
"designExports": 0,
"tokens": {
"total": 69489123,
"input": 2627914,
"output": 361338,
"cacheWrite": 15878681,
"cacheInput": 50621190
}
}
},
// ...
]
}For more details on the keys provided within the response, visit the following sections within this doc:
A designExport represents a single conversion from a design tool like Figma into code.
Design exports are tracked separately from AI chat events because they represent a distinct workflow: transforming visual designs into code rather than iterating on existing code through conversational AI.
Each design export is assigned a unique ID and counted once, even if code is generated from it multiple times. In API metrics, design exports are counted once per reporting period.
Each Builder Space can have multiple Projects, each of which can be connected to a repository. These API endpoints return Projects by Organization or by Space created within a certain timeframe.
Retrieves Project data for an entire Organization.
Include your Organization's Private Key within the Authorization header. Augment your request with the following query parameters:
| Parameter | Required? | Description |
|---|---|---|
startDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
endDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
sortBy | No | Value must be one of |
A sample response is included below:
{
"data": [
{
"projectId": "project-id",
"projectName": "Your Project Name",
"metrics": {
"linesAdded": 2403,
"linesRemoved": 723,
"linesAccepted": 280,
"userPrompts": 17,
"creditsUsed": 79.702,
"activeUsers": 3,
"prsMerged": 7
}
},
// ...
]
}For more details on the keys provided within the response, visit the following sections within this doc:
Retrieves Project data for a single Space.
Include your Space's Private Key within the Authorization header. Augment your request with the following query parameters:
| Parameter | Required? | Description |
|---|---|---|
startDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
endDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
sortBy | No | Value must be one of |
A sample response is included below:
{
"data": [
{
"projectId": "project-id",
"projectName": "Your Project Name",
"metrics": {
"linesAdded": 2403,
"linesRemoved": 723,
"linesAccepted": 280,
"userPrompts": 17,
"creditsUsed": 79.702,
"activeUsers": 3,
"prsMerged": 7
}
},
// ...
]
}For more details on the keys provided within the response, visit the following sections within this doc:
An event represents a single AI-assisted code generation interaction. Events are logged whenever a user or or user-directed agent performs an action that consumes AI credits or generates code.
An event would be when one of the following occurs: new code is generated, existing code is modified, or when a pull request was created, merged, or closed.
Retrieves particular events that occurred, such as code generation, at the organization level.
Include your Organization's Private Key within the Authorization header. Augment your request with the following query parameters:
| Parameter | Required? | Description |
|---|---|---|
startDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
endDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
A sample response is included below. Keep in mind that the response is paginated if there are hundreds of events.
{
"data": [
{
"eventId": "EVENT_ID",
"timestamp": "2025-07-29T21:33:57.331Z",
"feature": "fusion",
"userId": "USER_ID",
"userEmail": "USER_EMAIL",
"spaceId": "SPACE_ID",
"spaceName": "My Fusion Space",
"metadata": { "tokensUsed": 57842 },
},
// ...
],
"pagination": {
"page": 1,
"limit": 100,
"total": 8039,
"totalPages": 81,
"hasNext": true,
"hasPrevious": false,
}
}For more details on the keys provided within the response, visit the following section within this doc:
Retrieves particular events that occurred, such as code generation, at the Space level.
Include your Space's Private Key within the Authorization header. Augment your request with the following query parameters:
| Parameter | Required? | Description |
|---|---|---|
startDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
endDate | Yes | Date in YYYY-MM-DD format. This date value is inclusive. |
feature | No | Comma-separated list of features to filter by. More details on features are listed below. |
framework | No | Filter by specific framework. |
userId | No | Filter by specific user ID. |
projectId | No | Filter by specific Project ID. |
A sample response is included below. Keep in mind that the response is paginated if there are hundreds of events.
{
"data": [
{
"eventId": "EVENT_ID",
"timestamp": "2025-07-29T21:33:57.331Z",
"feature": "fusion",
"userId": "USER_ID",
"userEmail": "USER_EMAIL",
"spaceId": "SPACE_ID",
"spaceName": "My Fusion Space",
"metadata": { "tokensUsed": 57842 },
},
// ..
],
"pagination": {
"page": 1,
"limit": 100,
"total": 3825,
"totalPages": 39,
"hasNext": true,
"hasPrevious": false,
}
}For more details on the keys provided within the response, visit the following section within this doc:
A feature represents the source of an event. It could be within a Fusion Space or it could be from running an indexing of design components.
The feature key could have several values:
| Value | Description |
|---|---|
fusion | Code generation and AI-assisted development within the Builder application. |
editor-ai | AI-powered editing within the Visual Editor's Interact panel. |
cli | Code generation initiated from the command-line interface, with the Builder CLI. |
builder-code-panel | Code panel interactions within the Visual Editor. |
repo-indexing | Repository indexing operations for codebase analysis. |
Agent variants, such as fusion-agent or editor-ai-agent, may also appear when operations are performed by automated agents.
Each API response contains several keys. Each key is described below.
| Key | Description |
|---|---|
linesAdded | The number of lines of code added by AI code generation or in a pull request. |
linesRemoved | The number of lines of code removed or deleted by AI code generation or in a pull request. |
totalLines | Total lines modified, calculated as |
linesAccepted | Number of code lines accepted or committed from Builder Develop, the IDE extension. Tracked when users explicitly accept AI-generated code changes in their editor. This represents code that was committed to the codebase from Develop sessions. |
| Key | Description |
|---|---|
users | Count of unique or distinct users who were active during the time period. |
userPrompts | Count of user-initiated prompts or interactions, such as user questions or requests, with the AI. |
events | Total number of code generation or AI interaction events. |
| Key | Description |
|---|---|
designExports | Number of design component exports or Visual Copilot (VCP) references or exports. |
prsMerged | Number of pull requests that were merged. These are tracked separately from code generation. |
These fields are available in the tokens object for Space-level and user-level metrics endpoints.
| Key | Description |
|---|---|
tokens.total | Total LLM tokens consumed, calculated as |
tokens.input | Input or prompt tokens sent to the LLM. |
tokens.output | Output or completion tokens generated by the LLM. |
tokens.cacheWrite | Cache write tokens, used for storing prompt caching data. |
tokens.cacheInput | Cache input tokens, retrieved from cached prompts to reduce costs. |
These fields are available only at the user level.
| Key | Description |
|---|---|
creditsUsed | AI credits consumed by the user, rounded to 3 decimal places. |
These fields appear in the events endpoints.
| Key | Description |
|---|---|
eventId | Unique identifier for the event. |
timestamp | Timestamp of when the event occurred. |
feature | Feature identifier, such as "fusion" or "vcp". |
userId | User's unique identifier. |
userEmail | The event user's email address. |
spaceId | The Space's uniqued identifier. |
spaceName | Human-readable version of the Space name. |
designExportId | Visual Copilot component export identifier, if applicable. |
metadata.tokensUsed | Tokens consumed for this specific event. |
metadata.linesOfCode | Total lines of code for this event, formatted as a string. |
metadata.linesOfCodeAdded | Lines of code added in this event, formatted as a string. |
metadata.linesOfCodeRemoved | Lines of code removed in this event, formatted as a string. |
These fields appear in the summary object of metrics responses.
| Key | Description |
|---|---|
totalLinesGenerated | Sum of all |
totalLinesAccepted | Sum of all |
totalUsers | Total unique users across all periods. |
totalUserPrompts | Sum of all user prompts across all periods. |
totalDesignExports | Sum of all design exports across all periods. |
totalPRsMerged | Sum of all merged PRs across all periods. |
totalCreditsUsed | Sum of all credits used across all periods. |
These fields appear in the spaces array within organization-level metrics responses.
| Key | Description |
|---|---|
spaceId | Unique identifier for the Space. |
spaceName | Human-readable version of the Space name. |
linesAdded | Lines added within this Space for the period. |
linesRemoved | Lines removed within this Space for the period. |
totalLines | Total lines modified in this Space for the period. |
linesAccepted | Lines accepted within this Space for the period. Only available for Develop. |
The following errors may occur when making requests to this API endpoint.
| Status | Description |
|---|---|
400 | The date format is invalid, or a required parameter is missing. |
404 | The Organization or Space is not found or the request is not authorized. |
500 | An internal server error has occurred. |
Visit documentation for other Builder APIs, or learn more about how Agent Credits work within Builder.