# How the Cursor Admin API Usage Import Process Works in agentsview

> Learn how the agentsview usage cursor command imports Cursor Admin API usage data through a four-stage pipeline, including configuration loading, date range resolution, and deduplication into a local SQLite archive.

- Repository: [Kenn Software/agentsview](https://github.com/kenn-io/agentsview)
- Tags: how-to-guide
- Published: 2026-07-04

---

**The `agentsview usage cursor` command imports Cursor Admin API usage data through a four-stage pipeline that loads configuration, resolves date ranges, paginates through the filtered-usage-events endpoint, and deduplicates records into a local SQLite archive.**

The *agentsview* open-source CLI tool provides organizations with a reliable way to archive Cursor IDE telemetry for offline analysis and compliance reporting. Understanding the Cursor Admin API usage import process reveals how the tool bridges remote usage data with local storage through a deterministic, idempotent workflow.

## The Four-Stage Import Pipeline

The import workflow implemented in [`cmd/agentsview/usage_cursor.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/usage_cursor.go) orchestrates four distinct stages to move data from the Cursor Admin API into the local archive.

### Configuration Loading

The process begins by invoking `config.LoadMinimal()` to retrieve the global configuration settings. This loads the `cursor_admin_api_key` required for authentication, along with optional default values for `cursor_admin_email` or user ID filters and the target timezone. These settings establish the authentication context and default query parameters for the subsequent API requests.

### Date-Range Resolution

The command determines the temporal scope through `resolveCursorUsageWindow`, defined in [`cmd/agentsview/usage_cursor.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/usage_cursor.go). If the `--all` flag is provided, the range spans the entire available epoch. Otherwise, the function parses the `--since` and `--until` CLI arguments, falling back to sensible defaults based on the current date when these flags are omitted. This resolution produces precise Unix timestamps that bound the API query.

### Fetching from the Cursor Admin API

The HTTP client initialization occurs through `newCursorUsageClient(apiKey)`, which creates a `cursorusage.Client` instance configured with the Admin API credentials. The client executes a paginated `POST /teams/filtered-usage-events` request, where the request body contains the resolved start and end timestamps, the page size limit, and optional `email` or `userId` filters.

Pagination is handled by `FetchAllUsageEvents` in [`internal/cursorusage/client.go`](https://github.com/kenn-io/agentsview/blob/main/internal/cursorusage/client.go), which repeatedly invokes `ListUsageEvents` until all pages are exhausted. This loop manages empty page responses, respects total-count limits, and adjusts for page-size exhaustion, ensuring complete data retrieval without missing records.

### Persisting to the Local SQLite Archive

Each `cursorusage.UsageEvent` struct undergoes transformation into a `db.CursorUsageEvent` before storage. This conversion process, located in [`cmd/agentsview/usage_cursor.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/usage_cursor.go), converts timestamps to RFC-3339Nano format strings and maps the token consumption metrics to the database schema.

The `db.InsertCursorUsageEvents` function in [`internal/db/cursor_usage_events.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/cursor_usage_events.go) handles the actual persistence. It implements deduplication by computing a SHA-256 fingerprint for each record using the `cursorUsageEventDedupKey` helper, ensuring that re-running the import with overlapping date ranges does not create duplicate entries. Upon completion, the command outputs a summary indicating the number of events successfully stored.

## Usage Examples

### Command-Line Import

Execute the import directly from your terminal to fetch usage data for a specific user within a date range:

```bash
agentsview usage cursor \
    --since 2023-01-01 \
    --until 2023-12-31 \
    --page-size 200 \
    --email user@example.com

```

### Programmatic Integration

For custom tooling or automation, instantiate the client directly and handle the events slice:

```go
import (
    "context"
    "time"
    "github.com/kenn-io/agentsview/internal/cursorusage"
)

func importCursor(apiKey string) error {
    client := cursorusage.NewClient(apiKey)
    events, err := client.FetchAllUsageEvents(context.Background(), cursorusage.Query{
        StartDate: time.Now().AddDate(0, -1, 0), // last month
        EndDate:   time.Now(),
        PageSize:  100,
    })
    if err != nil {
        return err
    }
    // events contains []cursorusage.UsageEvent
    // Transform and insert via db.InsertCursorUsageEvents as needed
    return nil
}

```

## Key Implementation Files

The import pipeline spans three primary packages:

- **[`cmd/agentsview/usage_cursor.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/usage_cursor.go)** – Implements the CLI command interface, configuration handling, date-range resolution logic, and the transformation layer between API structs and database models.
- **[`internal/cursorusage/client.go`](https://github.com/kenn-io/agentsview/blob/main/internal/cursorusage/client.go)** – Defines the HTTP client for the Cursor Admin API, including the `FetchAllUsageEvents` pagination handler and the `ListUsageEvents` single-page request method.
- **[`internal/db/cursor_usage_events.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/cursor_usage_events.go)** – Manages the SQLite schema, the SHA-256 deduplication fingerprint logic (`cursorUsageEventDedupKey`), and the `InsertCursorUsageEvents` batch insertion function.

## Summary

- **The `agentsview usage cursor` command** provides the primary interface for importing Cursor Admin API usage data into the local archive.
- **Configuration** relies on `config.LoadMinimal()` to retrieve the `cursor_admin_api_key` and optional filtering defaults.
- **Date-range resolution** supports explicit `--since`/`--until` flags, the `--all` epoch flag, or sensible defaults via `resolveCursorUsageWindow`.
- **API pagination** is handled automatically by `FetchAllUsageEvents`, which consumes the `POST /teams/filtered-usage-events` endpoint until all pages are retrieved.
- **Deduplication** occurs at the database layer using SHA-256 fingerprints computed by `cursorUsageEventDedupKey`, ensuring idempotent imports.

## Frequently Asked Questions

### How does the agentsview CLI handle authentication with the Cursor Admin API?

The CLI loads the `cursor_admin_api_key` value from the global configuration file via `config.LoadMinimal()`. This key is passed to `newCursorUsageClient()` to initialize the `cursorusage.Client` with a default HTTP client configured to include the API key in request headers, as implemented in [`internal/cursorusage/client.go`](https://github.com/kenn-io/agentsview/blob/main/internal/cursorusage/client.go).

### What happens if I run the import command multiple times for overlapping date ranges?

The import process is idempotent. The `db.InsertCursorUsageEvents` function calculates a SHA-256 fingerprint for each event using `cursorUsageEventDedupKey`, which incorporates unique event identifiers. Duplicate fingerprints are rejected at the database level, preventing duplicate records while ensuring new events are still captured.

### Can I filter the usage data by specific team members during import?

Yes. The command accepts optional `--email` and `--userId` flags that are passed directly to the Cursor Admin API request body. These filters are also configurable as defaults (`cursor_admin_email`) in the configuration file, allowing you to scope imports to specific users without specifying flags on every execution.

### Where is the imported Cursor usage data stored locally?

All imported events are persisted to a local SQLite database file. The `db.CursorUsageEvent` schema in [`internal/db/cursor_usage_events.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/cursor_usage_events.go) defines the table structure, storing converted RFC-3339Nano timestamps, token metrics, and deduplication hashes for efficient querying and archival.