Source: https://docs.sogni.ai/api-reference/worker-analytics/

# Worker analytics

Behind the totals: people, hardware, and work getting done.

[![Sogni's pink sloth at a GPU workstation in a residential garage, with neighbouring homes across the street.](https://docs.sogni.ai/assets/api-mascot-neighbourhood-v1-1536.webp)](https://docs.sogni.ai/assets/api-mascot-neighbourhood-v1-1536.webp)

The network has neighbours. Artwork made with Sogni.

Base URL: `https://api.sogni.ai`. The aggregate analytics endpoints below are **public and rate-limited**. They do not require an API key. Wallet and NFT identifiers select aggregate activity.

For private balances and subscription-pool claims, use the authenticated [account and earnings endpoints](https://docs.sogni.ai/api-reference/account-and-usage/). Do not mistake a public analytics estimate for settled money.

## [#](https://docs.sogni.ai/api-reference/worker-analytics/#daily-totals-and-batched-worker-reads)Daily totals and batched worker reads

| Endpoint | Query parameters | Result location |
| --- | --- | --- |
| `GET /v1/analytics/day` | `address` for one wallet; optional `date=YYYY-MM-DD`, `network=fast` or `relaxed`. Omitting `address` selects aggregate network/global totals. | `data.analytics`, `data.date` |
| `GET /v1/analytics/lifetime` | `address` for one wallet, or `nft` with up to 40 comma-separated NFT IDs (summed); omit both for network totals. Optional `network=fast` or `relaxed` (not with `nft`), `keys` as comma-separated fields. | `data` is the analytics map. |
| `GET /v1/analytics/day/nft/:nftTokenId` | Optional `date` and `keys`. | `data.analytics`, `data.date` |
| `GET /v1/analytics/lifetime/nft/:nftTokenId` | Optional `keys`. | `data` is the analytics map. |
| `GET /v1/analytics/day/nfts` | Required `tokenIds`, comma-separated positive integer IDs, **at most 50**; optional `date`, `keys`. | `data.analytics` is keyed by NFT ID; `data.date` is the requested date. |

Dates use UTC calendar days and default to the current UTC date. UTC midnight is 5 PM PT on the preceding date during daylight time, or 4 PM PT during standard time. NFT workers without recorded activity return empty maps. An unknown wallet can return `404`; an empty map is not proof that a worker is currently offline. Analytics values are numeric strings and absent counters should be handled explicitly.

Prefer one batched request to one request per GPU:

```
curl --fail-with-body --get 'https://api.sogni.ai/v1/analytics/day/nfts' \
  --data-urlencode 'tokenIds=1,6,8' \
  --data-urlencode 'keys=jobCompleteWorker,connectedSecWorker,workSecWorker'
```

Useful fields, where recorded, include `jobCompleteWorker`, `jobErrorWorker`, `connectedSecWorker`, `workSecWorker`, and `renderSecCompleteWorker`. Newer worker time counters include `modelSwitchSecWorker`, `primingSecWorker`, `testJobSecWorker`, `routineCooldownSecWorker` (configured rests and readiness buffers), and `penaltyCooldownSecWorker` (time held back after failures). Time fields ending in `SecWorker` are seconds. Connected time, work time, and completed-job render time describe different quantities; do not use them interchangeably.

## [#](https://docs.sogni.ai/api-reference/worker-analytics/#daily-event-charts)Daily event charts

`GET /v1/analytics/chart/daily/events/query` accepts:

-   Required `query`: comma-separated event names, such as `jobCompleteWorker,jobErrorWorker,renderSecCompleteWorker`.
-   Optional `address` **or** `nftTokenId`, never both. The network-wide counters `uloginWorkerAddressFast`, `uloginWorkerAddressRelaxed`, `activeWorkerNFT`, and `workerOnlineSnapshotFast`, `...Relaxed`, and `...Total` ignore `address`, `nftTokenId`, and `network` for every event in the same query, so request them separately.
-   Optional `network=fast` or `relaxed` for wallet/global reads. Do not combine `network` with `nftTokenId` on this endpoint.
-   `count`: 1–120 days, default 7 when no start date is supplied.
-   Optional `startDate=YYYY-MM-DD`. Supply `count` too when requesting historical windows; a start date alone runs through today and cannot span more than 120 days.

```
curl --fail-with-body --get 'https://api.sogni.ai/v1/analytics/chart/daily/events/query' \
  --data-urlencode 'nftTokenId=1' \
  --data-urlencode 'query=jobCompleteWorker,jobErrorWorker' \
  --data-urlencode 'count=7'
```

The response contains `data.first`, `last`, `count`, `fields`, and `analytics`. Day keys in `analytics` are Unix **seconds** at UTC midnight, not milliseconds. A one-event query maps each day to a numeric string; a multi-event query maps each day to an array of numeric strings aligned with the returned `data.fields` order (usually alphabetical; always index by `data.fields`). Invalid fields return `400` with `supportedOptions`; do not send arbitrary event names.

## [#](https://docs.sogni.ai/api-reference/worker-analytics/#per-model-activity)Per-model activity

`GET /v1/analytics/chart/daily/model-use/query` accepts:

-   `address` with required `role=worker` or `artist`, **or** `nftTokenId` with `network=fast` and optional `role=worker`.
-   Optional `network=fast` or `relaxed`; required for wallet queries that set `includeSpark=true`.
-   Optional comma-separated `models`, `startDate`, and `count` (1–90, default 7). A resolved date range cannot exceed 90 days; use bounded windows for older history.
-   Optional `includeSpark=true` to include estimated Spark activity.

Results are under `data.analytics`, with optional `data.sparkAnalytics` and top-level `metadata`.

`GET /v1/analytics/model-use/lifetime` returns network-wide lifetime render counts per model in `data.analytics` (model ID to numeric string). Optional `network=fast` or `relaxed` narrows it, and `includeSpark=true` adds `data.sparkAnalytics`, recorded forward-only from `metadata.networkModelTrackingStartDate`. Each day's value contains model counters. Read tracking start dates in `metadata`: network/NFT/Spark attribution is forward-only, so missing old attribution is not proof of no historical work. Estimated Spark is activity attribution, not a claimable balance.

`GET /v1/model-renders/user-stats` provides a paginated per-model summary. Pass `address` or `username` with `role=worker` or `artist`, optional `network`, `period=lifetime` or `day`, and optional `date` for a day. Alternatively use `nftTokenId`, `role=worker`, and `network=fast`. Each item has `modelId`, `renderCount`, optional `rank`, and `sparkValue` when `network` is set, and the response includes `totalModels` and `totalPages`. `page` starts at 1; `limit` defaults to 50 and is capped at 1,000. Prefer `includeRank=false` if you only need counts. Results are under `data.modelStats`; pagination and tracking information accompany the response. Pagination bounds the returned page, not necessarily all server-side work.

## [#](https://docs.sogni.ai/api-reference/worker-analytics/#responsible-polling-and-access-boundaries)Polling

Use short, explicit chart windows, batch NFT reads, and cache the results in your integration. Refresh analytics around once per minute, not on every UI render. These reads share a per-client rate limit. On `429`, stop and wait: exceeding the limit can block further requests for several minutes, and `Retry-After` may be absent. Never repeatedly retry malformed `400` requests. These are aggregated counters, not a raw historical-job export.

See [model discovery and live demand](https://docs.sogni.ai/api-reference/model-discovery/) for current worker supply and queues.