Python SDK - Devin Docs

This documentation is for the federal deployments of Devin. Back to Devin Docs

The Python SDK (windsurf_analytics.py) is a command-line client for the endpoints in the federal API: usage reports, ACU consumption, group management, and user ACU caps. Download the script from the Analytics page of your deployment’s portal by selecting Download SDK, or contact your Cognition representative.

Requirements

Python 3
The requests library: pip install requests

Authentication

Every command takes these shared flags:

Flag	Description
`--service-key`	Service key for authentication. Can also be set via the `WINDSURF_SERVICE_KEY` environment variable.
`--api-url`	Base URL of your deployment’s API server (`https://<your-server>`). HTTPS is required.

The service key’s role must carry the permission required by each command — see the permission table. All analytics commands also require a team tier with analytics API access.

Commands

Command	Endpoint	Required permission
`usage` (default)	`/UserPageAnalytics` + `/CascadeAnalytics`	Teams Read-Only
`acu-consumption`	`/Analytics`	Analytics Read
`list-groups`	`/ListGroups`	Teams Read-Only
`get-group`	`/GetGroup`	Teams Read-Only
`create-group`	`/CreateGroup`	Teams Update
`update-group`	`/UpdateGroup`	Teams Update
`delete-group`	`/DeleteGroup`	Teams Update
`list-group-members`	`/ListGroupMembers`	Teams Read-Only
`add-group-members`	`/AddGroupMembers`	Teams Update
`remove-group-members`	`/RemoveGroupMembers`	Teams Update
`get-user-acu-cap`	`/GetUserAcuCap`	Teams Read-Only
`update-user-acu-cap`	`/UpdateUserAcuCap`	Teams Update

Running the script without a command (the original invocation) runs the usage report.

Output and errors

All commands print JSON to stdout. Paginated results (ACU consumption user rows, list-groups, list-group-members) are automatically followed to the last page and merged into a single response. API errors are printed to stderr as Error calling <endpoint> (HTTP <status>): code: message and the script exits with status 1. Invalid flag combinations are rejected before any request is sent, with exit status 2.

Examples

Per-user usage report

python windsurf_analytics.py \
    --service-key YOUR_SERVICE_KEY \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z \
    --end 2025-03-31T23:59:59Z

ACU consumption

# Team ACU total plus per-user rows for the current billing cycle
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --current-cycle --include-team-total --team-user-rows

# Historical per-group breakdown (window must span at most 90 days),
# with per-user rows for one group
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z --end 2025-03-31T23:59:59Z \
    --group-id GROUP_A_ID --group-user-rows GROUP_A_ID

acu-consumption flags: --current-cycle or --start/--end select the period; --include-team-total, repeatable --group-id (max 100), and mutually exclusive --team-user-rows / --group-user-rows GROUP_ID select the data; --page-size tunes the per-request page size (all pages are fetched regardless). At least one data selection flag is required. A group-scoped key can select only its assigned group and cannot request team totals or team user rows.

Group management

# List groups and read one group
python windsurf_analytics.py list-groups --api-url https://your-server.com
python windsurf_analytics.py get-group --api-url https://your-server.com \
    --group-id GROUP_ID

# Create a group, configure its models and ACU cap
python windsurf_analytics.py create-group --api-url https://your-server.com \
    --name Engineering
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID \
    --cascade-models MODEL_UID_1,MODEL_UID_2 \
    --set-cycle-acu-limit 50

# Clear a group's model restriction or ACU cap. The service API requires a
# positive value when setting a group cap; clearing is a separate operation.
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID --clear-cascade-models --clear-cycle-acu-limit

# Manage membership (comma-separated emails, max 1000)
python windsurf_analytics.py add-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov,lead@agency.gov
python windsurf_analytics.py remove-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov

# Delete a group (idempotent)
python windsurf_analytics.py delete-group --api-url https://your-server.com \
    --group-id GROUP_ID

User ACU caps

# Read a user's configured and effective cap (select by --email or --user-id)
python windsurf_analytics.py get-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov

# Set a cap (0 blocks the user) or clear the override
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --set-cycle-acu-limit 25
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --clear-cycle-acu-limit

​Requirements

​Authentication

​Commands

​Output and errors

​Examples

​Per-user usage report

​ACU consumption

​Group management

​User ACU caps

Requirements

Authentication

Commands

Output and errors

Examples

Per-user usage report

ACU consumption

Group management

User ACU caps