---
title: "Get usage report"
method: GET
path: "/api/v1/external/analytics/usage"
tags: ["Analytics"]
---

# Get usage report

`GET /api/v1/external/analytics/usage`

## Request

- Base URL: `https://api.wove.com`
- URL: `https://api.wove.com/api/v1/external/analytics/usage`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/wove/apis/wove-external-api/docs/api/v1/external/analytics/usage/get.ts> (a function with typed inputs; its response is checked against the schema)

Your organization's usage report: active users, documents processed, quote assignments,
edits and shipments / customs entries pushed to your TMS, per day or week, plus a per-user
breakdown. The same report as the dashboard's usage card and CSV export. Requires `analytics:read`.

The window is `startDate`/`endDate` if given, else the last `days` UTC days (today included),
else the last `weeks` Monday-aligned UTC weeks. Windows of 14 days or less are bucketed by day,
longer ones by week, with the first and last week clipped to the window. At most 366 days.

## Query parameters

- `startDate` string, date-time
- `endDate` string, date-time
- `days` integer
- `weeks` integer

## Response `200`

Usage report retrieved successfully

- object
  - `success` boolean
  - `data` UsageAnalytics
    - `granularity` 'day' | 'week'
    - `rangeStart` string, date-time: Start of the window (UTC)
    - `rangeEnd` string, date-time: End of the window (UTC); now, for a rolling window
    - `buckets` UsageAnalyticsBucket[]
      - `bucketStart` string, date: First UTC day of the bucket inside the window
      - `bucketEnd` string, date: Last UTC day of the bucket inside the window, inclusive
      - `label` string
      - `activeUsers` integer: Distinct users who performed any tracked action in the bucket
      - `documentsProcessed` integer
      - `quotesAssigned` integer
      - `assignmentActions` integer
      - `fieldEdits` integer: Field and rate edits
      - `syncedShipments` integer: Distinct top-level shipments successfully pushed to your TMS in the bucket. A shipment pushed again counts in the bucket of its latest successful push.
      - `syncedShipmentsAutomated` integer: Of those, pushed by automation or webhook
      - `syncedShipmentsManual` integer: Of those, pushed by a user
      - `syncedCustomsEntries` integer: Distinct customs entries successfully pushed to your TMS in the bucket
      - `syncedCustomsEntriesAutomated` integer
      - `syncedCustomsEntriesManual` integer
    - `userBreakdown` UsageAnalyticsUser[]: Sorted by totalActions, highest first
      - `userId` string
      - `userName` string: The user's name, or their email when no name is set
      - `documentsProcessed` integer
      - `quotesAssigned` integer
      - `assignmentActions` integer
      - `fieldEdits` integer
      - `syncedShipments` integer: Shipments this user pushed to the TMS by hand
      - `syncedCustomsEntries` integer: Customs entries this user pushed to the TMS by hand
      - `activeBuckets` integer: Buckets (days or weeks, per granularity) in which the user was active
      - `totalActions` integer

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication required or invalid credentials
- `403`: Insufficient permissions

---

[API](https://skmtc.dev/wove/apis/wove-external-api.md) - [All operations](https://skmtc.dev/wove/apis/wove-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wove/apis/wove-external-api/revisions/37290e267e07?raw)