# 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](/content/account/space/index.html) 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](/content/c/docs/settings#space-settings/index.html).
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](/content/c/docs/private-models/index.html).

## 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:

| 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 `day`, `week`, `month`, or `quarter`. Default value is `day`. |

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.

```bash
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:

```json
{
"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.

```bash
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:

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

| 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 `userPrompts`, `creditsUsed`, or `prsMerged`. Defaults to `creditsUsed`. |
| sortOrder | No | Orders a sorted list. Value must be one of `asc` or `desc`. Defaults to `desc`. |

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.

```bash
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:

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

| 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 `userPrompts`, `creditsUsed`, or `prsMerged`. Defaults to `creditsUsed`. |
| sortOrder | No | Orders a sorted list. Value must be one of `asc` or `desc`. Defaults to `desc`. |

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.

```bash
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:

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

| 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 `creditsUsed`, `linesAccepted`, `prsMerged`, or `userPrompts`. Default value is `creditsUsed`. |

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.

```bash
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:

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

| 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. |

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.

```bash
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:

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

| 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. |
| framework | No | Filter by specific framework. |
| userId | No | Filter by specific user ID. |
| projectId | No | Filter by specific Project ID. |

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.

```bash
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:

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

| 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 `linesAdded` + `linesRemoved`. |
| `linesAccepted` | Number of code lines accepted or committed from **Builder Develop**, the IDE extension. |

### User activity metrics

| 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. |

### Design and integration metrics

| Key | Description |
| --- | --- |
| `designExports` | Number of design component exports or Visual Copilot (VCP) references or exports. |
| `prsMerged` | Number of pull requests that were merged. |

### Token usage metrics

| Key | Description |
| --- | --- |
| `tokens.total` | Total LLM tokens consumed. |
| `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. |

### Cost metrics

| Key | Description |
| --- | --- |
| `creditsUsed` | AI credits consumed by the user, rounded to 3 decimal places. |

### Event metadata fields

| Key | Description |
| --- | --- |
| `eventId` | Unique identifier for the event. |
| `timestamp` | Timestamp of when the event occurred. |
| `feature` | Feature identifier. |
| `userId` | User's unique identifier. |
| `userEmail` | The event user's email address. |
| `spaceId` | The Space's unique identifier. |
| `spaceName` | Human-readable version of the Space name. |
| `metadata.tokensUsed` | Tokens consumed for this specific event. |

### Summary fields

| Key | Description |
| --- | --- |
| `totalLinesGenerated` | Sum of all `totalLines` across all periods. |
| `totalLinesAccepted` | Sum of all `linesAccepted` across all periods. |
| `totalUsers` | Total unique users across all periods. |
| `totalUserPrompts` | Sum of all user prompts across all periods. |

### Possible errors

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. |

## What's next

Visit documentation for other [Builder APIs](/content/c/docs/api-intro/index.html), or learn more about how [Agent Credits](/content/c/docs/agent-credits/index.html) work within Builder.