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. — 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. Do not mistake a public analytics estimate for settled money.

#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; optional `network=fast` or `relaxed`, `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. Time fields ending in SecWorker are seconds. Connected time, work time, and completed-job render time describe different quantities; do not use them interchangeably.

#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.
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 (do not assume it preserves your input ordering). Invalid fields return 400 with supportedOptions; do not send arbitrary event names.

#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. 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, role=worker, optional network, period=lifetime or day, and optional date for a day. Alternatively use nftTokenId, role=worker, and network=fast. 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.

#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. Reduce concurrency and honor 429 / Retry-After; never repeatedly retry malformed 400 requests. These are aggregated counters, not a raw historical-job export.

See model discovery and live demand for current worker supply and queues.