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
}
}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,
}
}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. |
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
}
}
},
// ...
]
}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.
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. |
granularity | No | Value must be one of |
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,
}
}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. |
granularity | No | Value must be one of |
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,
}
}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.
The following errors may occur when making requests to this API endpoint.
| Status | Description |
|---|---|
400 | The date or granularity format is invalid, or a required parameter is missing. This error is also returned when the date range for a request with a granularity of |
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.