How the Cursor Admin API Usage Import Process Works in agentsview

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

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:

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

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 defines the table structure, storing converted RFC-3339Nano timestamps, token metrics, and deduplication hashes for efficient querying and archival.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}