# Get Personal Connector Usage Statistics

div
strong
🔨 In Development
 — This section is still being developed and may change.


Retrieve usage statistics and billing information for a personal connector configuration. This endpoint provides detailed insights into how often tools are being used and how many neurons are being consumed.

This endpoint returns usage statistics for a specific personal connector configuration, including tool execution counts, neuron costs, execution times, and error rates. You can filter by date range and aggregate by different time periods.

#### Path Parameters

**`config_id`** string required
The ID of the personal connector configuration (e.g., `pconf_abc123`).

#### Query Parameters

**`startDate`** string optional
Start date for the usage period (ISO 8601 format). Defaults to 30 days ago.

**`endDate`** string optional
End date for the usage period (ISO 8601 format). Defaults to now.

**`aggregation`** string optional · Defaults to `day`
Time period for aggregation. Values: `hour`, `day`, `week`, `month`.

**`toolName`** string optional
Filter by specific tool name (e.g., `clickup_create_task`).

Get usage for last 30 days

```bash
curl https://api.freddy.aitronos.com/v1/personal-connectors/configurations/pconf_abc123/usage \
  -H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
import requests
import os

api_key = os.environ.get("FREDDY_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"}

response = requests.get(
    "https://api.freddy.aitronos.com/v1/personal-connectors/configurations/pconf_abc123/usage",
    headers=headers
)

print(response.json())
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/personal-connectors/configurations/pconf_abc123/usage', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.FREDDY_API_KEY}`
  }
});

const data = await response.json();
console.log(data);
```

Get usage for specific date range

```bash
curl "https://api.freddy.aitronos.com/v1/personal-connectors/configurations/pconf_abc123/usage?startDate=2025-10-01T00:00:00Z&endDate=2025-10-07T23:59:59Z" \
  -H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
import requests
import os

api_key = os.environ.get("FREDDY_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"}
params = {
    "startDate": "2025-10-01T00:00:00Z",
    "endDate": "2025-10-07T23:59:59Z"
}

response = requests.get(
    "https://api.freddy.aitronos.com/v1/personal-connectors/configurations/pconf_abc123/usage",
    headers=headers,
    params=params
)

print(response.json())
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/personal-connectors/configurations/pconf_abc123/usage?startDate=2025-10-01T00:00:00Z&endDate=2025-10-07T23:59:59Z', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.FREDDY_API_KEY}`
  }
});

const data = await response.json();
console.log(data);
```

Get usage for specific tool

```bash
curl "https://api.freddy.aitronos.com/v1/personal-connectors/configurations/pconf_abc123/usage?toolName=clickup_create_task" \
  -H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
import requests
import os

api_key = os.environ.get("FREDDY_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"}
params = {"toolName": "clickup_create_task"}

response = requests.get(
    "https://api.freddy.aitronos.com/v1/personal-connectors/configurations/pconf_abc123/usage",
    headers=headers,
    params=params
)

print(response.json())
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/personal-connectors/configurations/pconf_abc123/usage?toolName=clickup_create_task', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.FREDDY_API_KEY}`
  }
});

const data = await response.json();
console.log(data);
```

## Response

200 OK

```json
{
  "configurationId": "pconf_abc123",
  "configurationName": "My ClickUp Tasks",
  "personalConnectorId": "pcon_clickup",
  "period": {
    "startDate": "2025-09-07T00:00:00Z",
    "endDate": "2025-10-07T23:59:59Z",
    "aggregation": "day"
  },
  "summary": {
    "totalExecutions": 245,
    "successfulExecutions": 238,
    "failedExecutions": 7,
    "totalNeuronsCharged": 1837500,
    "averageExecutionTimeMs": 1450,
    "successRate": 0.971
  },
  "billing": {
    "baseFeeNeurons": 5000,
    "neuronsPerInterval": 100,
    "intervalSeconds": 0.1,
    "totalCost": 1837500,
    "estimatedMonthlyCost": 5512500
  },
  "toolBreakdown": [
    {
      "toolName": "clickup_create_task",
      "executions": 156,
      "successfulExecutions": 152,
      "failedExecutions": 4,
      "neuronsCharged": 1170000,
      "averageExecutionTimeMs": 1500,
      "successRate": 0.974
    },
    {
      "toolName": "clickup_list_tasks",
      "executions": 67,
      "successfulExecutions": 65,
      "failedExecutions": 2,
      "neuronsCharged": 502500,
      "averageExecutionTimeMs": 1250,
      "successRate": 0.970
    },
    {
      "toolName": "clickup_update_task",
      "executions": 22,
      "successfulExecutions": 21,
      "failedExecutions": 1,
      "neuronsCharged": 165000,
      "averageExecutionTimeMs": 1500,
      "successRate": 0.955
    }
  ],
  "timeSeries": [
    {
      "date": "2025-10-01",
      "executions": 34,
      "neuronsCharged": 255000,
      "averageExecutionTimeMs": 1420
    },
    {
      "date": "2025-10-02",
      "executions": 28,
      "neuronsCharged": 210000,
      "averageExecutionTimeMs": 1500
    },
    {
      "date": "2025-10-03",
      "executions": 41,
      "neuronsCharged": 307500,
      "averageExecutionTimeMs": 1500
    }
  ],
  "errors": [
    {
      "errorCode": "invalid_list_id",
      "errorMessage": "The specified list ID does not exist.",
      "count": 4,
      "lastOccurrence": "2025-10-07T14:30:00Z"
    },
    {
      "errorCode": "rate_limit_exceeded",
      "errorMessage": "ClickUp API rate limit exceeded.",
      "count": 3,
      "lastOccurrence": "2025-10-06T16:45:00Z"
    }
  ]
}
```

Errors

```json
{
  "error": {
    "type": "not_found_error",
    "message": "Personal connector configuration with ID 'pconf_abc123' not found.",
    "code": "configuration_not_found"
  }
}
```


```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid date range: startDate must be before endDate.",
    "code": "invalid_date_range"
  }
}
```


```json
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key"
  }
}
```

## Response Fields

### Summary

- **`totalExecutions`** - Total number of tool executions in the period
- **`successfulExecutions`** - Number of successful executions
- **`failedExecutions`** - Number of failed executions
- **`totalNeuronsCharged`** - Total neurons consumed
- **`averageExecutionTimeMs`** - Average execution time across all tools
- **`successRate`** - Success rate (0.0 to 1.0)


### Billing

- **`baseFeeNeurons`** - Base fee per tool execution
- **`neuronsPerInterval`** - Neurons charged per time interval
- **`intervalSeconds`** - Time interval for billing (e.g., 0.1 seconds)
- **`totalCost`** - Total neurons charged in the period
- **`estimatedMonthlyCost`** - Projected monthly cost based on current usage


### Tool Breakdown

Per-tool statistics showing which tools are used most frequently and their individual costs.

### Time Series

Usage data aggregated by the specified time period (hour, day, week, or month).

### Errors

Common errors encountered during tool executions, including error codes, messages, counts, and last occurrence timestamps.

## Use Cases

- **Cost Monitoring:** Track neuron consumption and estimate monthly costs
- **Usage Analytics:** Understand which tools are used most frequently
- **Performance Monitoring:** Identify slow-performing tools
- **Error Tracking:** Identify and troubleshoot recurring errors
- **Capacity Planning:** Plan for future usage based on trends
- **Budget Management:** Set alerts based on usage thresholds