NOLGIANOLGIADocs

Model APIs

Usage and activity

On this page
  1. Activity feed
  2. Credit usage summary
  3. Agent usage
  4. Organization usage
  5. Organization audit trail
    1. Export the trail
  6. Where assets are used

There are no per-request logs or latency analytics.

Use the activity feed to follow work, the credit ledger to account for spending, and the organization audit trail to see administrative changes. Each surface answers a different question; none is an HTTP request log.

Surface Question it answers Scope
GET /activity What was created, completed or changed? The caller's resources, optionally narrowed by project or agent session.
GET /billing/transactions/summary What credits moved in this period? Personal wallets or the current organization, subject to role.
GET /agent/usage What generations did my agent's token create? The caller's agent.
GET /organizations/{id}/usage What credits did organization members consume? The organization's consumed reservations.
GET /organizations/{id}/audit-events Who changed the organization? Owner or admin access.
GET /asset-usage Which compositions reference this asset? The caller's current composition documents.

Activity feed #

The feed is assembled at read time from existing jobs, assets, compositions and renders. It stores no separate event history. Every event has a human-readable summary of at most 160 characters and resource ids in refs.

Property Value
Order Newest first
Incremental polling Pass the newest at already seen as since; only strictly newer events are returned.
Page size limit defaults to 50, maximum 100.
Project filter project_id; a generation joins a project through its produced asset.
Session filter agent_session_id; excludes composition and render events without session attribution.
shellRead recent activity
curl --fail-with-body -sS 'https://api.nolgia.ai/v1/activity?limit=20' \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

This schema-built example shows a completed image job. It is not a production capture.

JSON200 activity response example
{
  "events": [
    {
      "at": "2026-09-21T03:34:00Z",
      "kind": "generation.succeeded",
      "summary": "Image generation succeeded (flux-pro)",
      "refs": {
        "job_id": "00000000-0000-4000-8000-000000000001",
        "asset_id": "00000000-0000-4000-8000-000000000002"
      }
    }
  ]
}
Parameter In Required Description
project_id query No Restrict the feed to events belonging to this project.
since query No Return only events strictly newer than this timestamp. Pass the newest at already seen to poll for increments.
agent_session_id query No Restrict the feed to events caused by the given chat session — the job's agent_session_id or an agent upload's metadata.agent_session_id. Scoped to the caller's own events. Composition and render events, which carry no session attribution, are excluded when this is set.
limit query No Maximum events to return.
Field Type Required Description
events array of ActivityEvent Yes Events newest first.
Field Type Required Description
at string Yes When the event happened (source-row timestamp).
kind ActivityEventKind Yes
summary string Yes Server-built human-readable one-liner.
error_detail string, nullable No User-facing failure reason for generation.failed, or the cancellation's plain message (what was refunded or charged) for generation.canceled; absent for every other event kind.
refs ActivityEventRefs Yes
Field Type Required Description
job_id string No
asset_id string No
composition_id string No
render_id string No
project_id string No
agent_session_id string No The chat session whose agent turn caused this event's job or asset — the job's agent_session_id, or an agent upload's metadata.agent_session_id.…

Credit usage summary #

The summary is the roll-up behind the billing usage chart. It counts the same ledger rows and uses the same access rules as GET /billing/transactions: in organization scope, owner, admin and billing roles can see everyone, while members and viewers see their own rows.

Property Value
Default window Current UTC calendar month
Custom window from inclusive, to exclusive, both RFC 3339; maximum 366 days
credits_used Generation, agent-turn and reserved render charge kinds, as a positive total
credits_refunded Refunds of those charges, as a positive total
credits_added Grants, top-ups and redemptions
by_day UTC dates with activity; fill missing days with zero in your chart
by_kind Signed net credits and row count for each kind present
shellSummarize a month
curl --fail-with-body -sS \
  'https://api.nolgia.ai/v1/billing/transactions/summary?from=2026-09-01T00%3A00%3A00Z&to=2026-10-01T00%3A00%3A00Z' \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

This schema-built example has one 12-credit charge and its full refund.

JSON200 credit summary example
{
  "from": "2026-09-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "scope": "personal",
  "credits_used": 12,
  "credits_refunded": 12,
  "credits_added": 0,
  "by_day": [ { "date": "2026-09-21", "credits_used": 12, "credits_refunded": 12 } ],
  "by_kind": [
    { "kind": "generation", "credits": -12, "count": 1 },
    { "kind": "refund", "credits": 12, "count": 1 }
  ]
}
Parameter In Required Description
from query No Inclusive window start (RFC 3339). Defaults to the first instant of the current UTC month.
to query No Exclusive window end (RFC 3339). Defaults to the first instant of the next UTC month.
member_id query No Organization context only; same rules as on GET /billing/transactions.
Field Type Required Description
from string Yes
to string Yes
scope BillingScope Yes
organization_id string No Set when scope is organization.
member_id string No Set when the summary is narrowed to one member's rows.
credits_used integer Yes
credits_refunded integer Yes
credits_added integer Yes Grants, top-ups and redemptions in the window.
by_day array of CreditUsageDay Yes
by_kind array of CreditUsageKindTotal Yes
Field Type Required Description
date string Yes UTC calendar day, YYYY-MM-DD.
credits_used integer Yes Generation, agent-turn and render charges taken that day, as a positive number.
credits_refunded integer Yes Refunds credited that day, as a positive number.
Field Type Required Description
kind CreditTransactionKind Yes
credits integer Yes Signed net of every row of this kind in the window.
count integer Yes

A generation charge appears when its hold is taken, before the job finishes. For settled organization spending, use Organization usage. For individual debits, refunds and resulting wallet balances, use the ledger.

Agent usage #

GET /agent/usage summarizes generations created with the current user's agent token. credits_spent counts generation credits consumed; it is not a count of all agent-turn charges. Use the billing ledger for the turn charges themselves.

shellRead agent usage
curl --fail-with-body -sS https://api.nolgia.ai/v1/agent/usage \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

This is a trimmed production agent-usage.json capture. Totals are intact; recent_jobs is shortened to its first job, and that job's provider request id and user id are omitted.

JSON200 agent usage excerpt
{
  "credits_spent": 15038,
  "jobs_total": 288,
  "recent_jobs": [
    {
      "completed_at": "2026-09-10T19:08:57.621139Z",
      "created_at": "2026-09-10T19:07:27.251676Z",
      "id": "4bd62272-67e1-4ce4-b9a7-13d982be3a49",
      "modality": "video",
      "model": "seedance-2.0-pro-t2v",
      "progress": 0,
      "status": "succeeded",
      "updated_at": "2026-09-10T19:08:57.621139Z"
    }
  ]
}
Field Type Required Description
credits_spent integer Yes Total credits consumed by generations the agent's token created.
jobs_total integer Yes Number of jobs created with the agent's token.
recent_jobs array of Job Yes
Field Type Required Description
id string Yes
modality Modality Yes
model string Yes
status JobStatus Yes
progress number, nullable No
created_at string Yes
updated_at string Yes
completed_at string, nullable No

Organization usage #

GET /organizations/{id}/usage counts consumed reservations against the organization's wallets, created within the requested window. Held reservations and released holds are excluded. Its total_credits therefore answers a different question from the ledger summary's gross credits_used.

Property Value
group_by member (default), model, or day
Default window Current UTC month; custom from/to use an inclusive start and exclusive end, up to 366 days
Owner, admin, billing All organization spending
Member, viewer Only their own spending
Non-member 404
shellGroup organization spending by model
curl --fail-with-body -sS \
  "https://api.nolgia.ai/v1/organizations/$ORGANIZATION_ID/usage?group_by=model" \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

This schema-built example groups three consumed image reservations into one model bucket.

JSON200 organization usage example
{
  "organization_id": "00000000-0000-4000-8000-000000000010",
  "from": "2026-09-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "group_by": "model",
  "total_credits": 12,
  "items": [ { "key": "flux-pro", "credits": 12, "jobs": 3 } ]
}
Parameter In Required Description
id path Yes Organization UUID.
from query No Inclusive window start (RFC 3339). Defaults to the first instant of the current UTC month.
to query No Exclusive window end (RFC 3339). Defaults to the first instant of the next UTC month.
group_by query No
Field Type Required Description
organization_id string Yes
from string Yes
to string Yes
group_by OrganizationUsageGroupBy Yes
total_credits integer Yes
items array of OrganizationUsageItem Yes
Field Type Required Description
key string Yes The member's user id, the model id (agent_turn for agent chat turns), or the UTC day as YYYY-MM-DD.
label string No The member's email for the member grouping; absent otherwise.
credits integer Yes Consumed credits in this bucket.
jobs integer Yes Consumed reservations in this bucket (one per generation or agent turn).

items[].key is a member id, model id, or UTC YYYY-MM-DD date. The model grouping uses agent_turn for agent chat turns. jobs counts consumed reservations, so it includes agent turns as well as generations.

Organization audit trail #

Owners and admins can read organization events newest first, filtered by exact action or actor user id. The audit trail records the actor and target of a change; it is separate from generation activity and billing usage.

shellRead organization audit events
curl --fail-with-body -sS \
  "https://api.nolgia.ai/v1/organizations/$ORGANIZATION_ID/audit-events?action=member.invited" \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

This schema-built example shows an invitation event. The ids and address are illustrative.

JSON200 audit response example
{
  "items": [
    {
      "id": "12345",
      "organization_id": "00000000-0000-4000-8000-000000000010",
      "actor_user_id": "00000000-0000-4000-8000-000000000011",
      "actor_email": "owner@example.com",
      "actor_api_key_id": null,
      "action": "member.invited",
      "target_type": "invitation",
      "target_id": "00000000-0000-4000-8000-000000000012",
      "metadata": {},
      "ip": null,
      "user_agent": null,
      "created_at": "2026-09-21T03:30:00Z"
    }
  ],
  "next_cursor": null
}
Parameter In Required Description
id path Yes Organization UUID.
cursor query No Opaque pagination cursor returned by a prior response.
limit query No Maximum items to return.
action query No Exact action filter (for example member.invited).
actor query No Filter on the acting user's id.
Field Type Required Description
items array of OrganizationAuditEvent Yes
next_cursor string, nullable Yes
Field Type Required Description
id string Yes Monotonic event id (also the pagination cursor).
organization_id string Yes
actor_user_id string, nullable Yes
actor_email string, nullable Yes Who acted: the member's email at the time of the event, the literal value NOLGIA staff for an action NOLGIA's own operators took on the organization (support or administration), or null when the actor is not resolvable.…
actor_api_key_id string, nullable Yes
action string Yes Dotted action, for example member.invited.
target_type string, nullable Yes
target_id string, nullable Yes
metadata object Yes
ip string, nullable Yes
user_agent string, nullable Yes
created_at string Yes

Export the trail #

Property Value
Endpoint GET /organizations/{id}/audit-events/export
Access Owner or admin on an Enterprise organization
Format text/csv, all events newest first
Team-plan refusal 402 Upgrade Required; buying credits does not unlock this plan feature
shellExport the audit trail
curl --fail-with-body -sS \
  "https://api.nolgia.ai/v1/organizations/$ORGANIZATION_ID/audit-events/export" \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -o audit-events.csv

The response is a CSV file rather than JSON. This schema-built example uses the verified export column order and the illustrative event above.

csv200 CSV export example
id,created_at,action,actor_user_id,actor_email,actor_api_key_id,target_type,target_id,ip,user_agent,metadata
12345,2026-09-21T03:30:00Z,member.invited,00000000-0000-4000-8000-000000000011,owner@example.com,,invitation,00000000-0000-4000-8000-000000000012,,,{}
Columns Meaning
id, created_at, action Event identity, timestamp and dotted action.
actor_user_id, actor_email, actor_api_key_id Actor and credential attribution when present.
target_type, target_id Resource affected by the change.
ip, user_agent Recorded request context when present.
metadata Event-specific JSON data encoded as a CSV field.

Where assets are used #

GET /asset-usage scans the caller's newest composition documents for asset references, including HTML files and the edits overlay. Repeat ids to narrow the result to particular assets.

shellFind compositions using an asset
curl --fail-with-body -sS \
  "https://api.nolgia.ai/v1/asset-usage?ids=$ASSET_ID" \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

This schema-built example shows one asset referenced by one composition.

JSON200 asset usage example
{
  "usage": [
    {
      "asset_id": "00000000-0000-4000-8000-000000000002",
      "compositions": [
        { "id": "00000000-0000-4000-8000-000000000020", "name": "Launch film", "project_id": null, "project_name": null }
      ]
    }
  ],
  "complete": true
}
Parameter In Required Description
ids query No Return usage only for these asset ids (repeat the param per id).
Field Type Required Description
usage array of AssetUsageEntry Yes
complete boolean Yes
Field Type Required Description
asset_id string Yes
compositions array of object Yes The user's compositions whose current document references the asset.
Composition field Meaning
id, name The composition whose current document references the asset.
project_id, project_name Optional, nullable project association.