Metrics API

Access Builder's code generation Metrics API for programmatic access to Fusion Space usage metrics.

What to know

• Generate a Private Key on your Space's Settings page to gain access to metrics data.
• Request Organization-level or Space-level metrics programmatically.

Private API Keys

A Private API Key is a server-side credential that grants write access to your Builder Space. Use Private Keys when you need to:

• Write or update content in your Builder Space programmatically
• Fetch content that should remain private and not be publicly accessible

Only users with Admin permissions can view or create Private Keys.

Tip: Keep your Private API Key secret. Anyone with a Private Key has write access to your Builder content. Only use it in API calls from your server, not calls from public client applications.

Manage Private API Keys

To manage the Private Keys for your Space:

1. Go to your Space Settings.
2. To the right of Private Keys, click the Edit button.
3. 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.

Get metrics

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.

Get Organization-level metrics

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:

Make a request to follow URL endpoint:

https://builder.io/api/v1/orgs/fusion/metrics

Example request

The following curl request summarizes all data for the entire month of July in 2025.

curl -G https://builder.io/api/v1/orgs/fusion/metrics \
 -d startDate=2025-07-01 \
 -d endDate=2025-07-31 \
 -d granularity='month' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer YOUR-PRIVATE-TOKEN'

Example response

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,
"mcpPrototypesPulled": 2,
"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,
"totalMcpPrototypesPulled": 2
}
}

Get Space-level metrics

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:

Make a request to follow URL endpoint, replacing :publicApiKey with your Space's Public API Key:

https://builder.io/api/v1/spaces/:publicApiKey/fusion/metrics

Example request

The following curl request summarizes all data for the entire month of July in 2025 for a specific Space.

curl -G https://builder.io/api/v1/spaces/:publicApiKey/fusion/metrics \
 -d startDate=2025-07-01 \
 -d endDate=2025-07-31 \
 -d granularity='month' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer YOUR-PRIVATE-TOKEN'

Example response

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,
"mcpPrototypesPulled": 2,
"tokens": {
"total": 336275030,
"input": 2716702,
"output": 1359459,
"cacheWrite": 24997783,
"cacheInput": 307201086
}
}
}
],
"summary": {
"totalLinesGenerated": 1106096,
"totalLinesAccepted": 0,
"totalUsers": 2,
"totalUserPrompts": 233,
"totalDesignExports": 0,
"totalMcpPrototypesPulled": 2
}
}

Get Organization-level user metrics

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:

Make a request to follow URL endpoint:

https://builder.io/api/v1/orgs/fusion/users

Example request

The following curl request requests user data for the entire month of January in 2024. The list is ordered by credits used.

curl -X GET https://builder.io/api/v1/orgs/fusion/users \
 -d startDate=2024-01-01 \
 -d endDate=2024-01-31 \
 -d sortBy=creditsUsed \
 -d orderBy=asc \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer YOUR-PRIVATE-TOKEN'

Example response

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
}
}
},
// ... 
]
}

Get Space-level user metrics

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:

Make a request to follow URL endpoint:

https://builder.io/api/v1/spaces/:publicApiKey/fusion/users

Example request

The following curl request summarizes all data for the entire month of July in 2025 for a specific Space.

curl -G https://builder.io/api/v1/spaces/:publicApiKey/fusion/users \
 -d startDate=2025-07-01 \
 -d endDate=2025-07-31 \
 -d sortBy=creditsUsed \
 -d orderBy=asc \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer YOUR-PRIVATE-TOKEN'

Example response

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
}
}
},
// ... 
]
}

Design exports

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.

Get Projects

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.

Get Organization-level Projects

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:

Make a request to follow URL endpoint:

https://builder.io/api/v1/orgs/fusion/projects

Example request

The following curl request returns Project data for the month of July in 2025.

curl -G https://builder.io/api/v1/orgs/fusion/projects \
 -d startDate=2025-07-01 \
 -d endDate=2025-07-31 \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer YOUR-PRIVATE-TOKEN'

Example response

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
}
},
// ... 
]
}

Get events

An event represents a single AI-assisted code generation interaction. Events are logged whenever a user or user-directed agent performs an action that consumes AI credits or generates code.

Get Organization-level events

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:

Make a request to follow URL endpoint:

https://builder.io/api/v1/orgs/fusion/events

Example request

The following curl request returns all events for the month of July in 2025.

curl -G https://builder.io/api/v1/orgs/fusion/events \
 -d startDate=2025-07-01 \
 -d endDate=2025-07-31 \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer YOUR-PRIVATE-TOKEN'

Example response

A sample response is included below:

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

Get Space-level events

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:

Make a request to follow URL endpoint:

https://builder.io/api/v1/spaces/:publicApiKey/fusion/events

Example request

The following curl request returns all events for the month of July in 2025.

curl -G https://builder.io/api/v1/spaces/:publicApiKey/fusion/events \
 -d startDate=2025-07-01 \
 -d endDate=2025-07-31 \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer YOUR-PRIVATE-TOKEN'

Example response

A sample response is included below:

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

Features

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.

API response keys

Each API response contains several keys. Each key is described below.

Core code metrics

User activity metrics

Design and integration metrics

Token usage metrics

Cost metrics

Event metadata fields

Summary fields

Possible errors

The following errors may occur when making requests to this API endpoint.

What's next

Visit documentation for other Builder APIs, or learn more about how Agent Credits work within Builder.