---
title: Usage and activity
description: "What ran, what it cost and who did it: the activity feed, usage roll-ups, the organization audit trail, and where assets are used."
---

# Usage and activity

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. |

```bash title="Read 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.

```json title="200 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"
      }
    }
  ]
}
```

<!-- gen:params op=getActivity -->
| 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. |
<!-- /gen -->

<!-- gen:fields schema=ActivityFeed -->
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | array of `ActivityEvent` | Yes | Events newest first. |
<!-- /gen -->

<!-- gen:fields schema=ActivityEvent -->
| 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 |  |
<!-- /gen -->

<!-- gen:fields schema=ActivityEventRefs -->
| 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`.… |
<!-- /gen -->

> [!NOTE]
> A project-filtered feed cannot show a queued or running generation that has not produced an asset, or one that failed before output. Use the unfiltered feed or poll the job directly when you need those states.

## 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 |

```bash title="Summarize 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.

```json title="200 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 }
  ]
}
```

<!-- gen:params op=getCreditUsageSummary -->
| 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`. |
<!-- /gen -->

<!-- gen:fields schema=CreditUsageSummary -->
| 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 |  |
<!-- /gen -->

<!-- gen:fields schema=CreditUsageDay -->
| 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. |
<!-- /gen -->

<!-- gen:fields schema=CreditUsageKindTotal -->
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `CreditTransactionKind` | Yes |  |
| `credits` | integer | Yes | Signed net of every row of this kind in the window. |
| `count` | integer | Yes |  |
<!-- /gen -->

A generation charge appears when its hold is taken, before the job finishes. For settled organization spending, use [Organization usage](#organization-usage). For individual debits, refunds and resulting wallet balances, use the [ledger](./billing.html#itemized-transactions).

## 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.

```bash title="Read 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.

```json title="200 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"
    }
  ]
}
```

<!-- gen:fields schema=AgentUsage -->
| 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 |  |
<!-- /gen -->

<!-- gen:fields schema=Job only=id,modality,model,status,progress,created_at,updated_at,completed_at -->
| 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 |  |
<!-- /gen -->

## 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` |

```bash title="Group 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.

```json title="200 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 } ]
}
```

<!-- gen:params op=getOrganizationUsage -->
| 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 |  |
<!-- /gen -->

<!-- gen:fields schema=OrganizationUsage -->
| 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 |  |
<!-- /gen -->

<!-- gen:fields schema=OrganizationUsageItem -->
| 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). |
<!-- /gen -->

`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.

```bash title="Read 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.

```json title="200 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
}
```

<!-- gen:params op=listOrganizationAuditEvents -->
| 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. |
<!-- /gen -->

<!-- gen:fields schema=OrganizationAuditEventList -->
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of `OrganizationAuditEvent` | Yes |  |
| `next_cursor` | string, nullable | Yes |  |
<!-- /gen -->

<!-- gen:fields schema=OrganizationAuditEvent -->
| 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 |  |
<!-- /gen -->

### 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 |

```bash title="Export 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.

```csv title="200 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.

```bash title="Find 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.

```json title="200 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
}
```

<!-- gen:params op=listAssetUsage -->
| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `ids` | query | No | Return usage only for these asset ids (repeat the param per id). |
<!-- /gen -->

<!-- gen:fields schema=AssetUsage -->
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `usage` | array of `AssetUsageEntry` | Yes |  |
| `complete` | boolean | Yes |  |
<!-- /gen -->

<!-- gen:fields schema=AssetUsageEntry -->
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `asset_id` | string | Yes |  |
| `compositions` | array of object | Yes | The user's compositions whose current document references the asset. |
<!-- /gen -->

| Composition field | Meaning |
| --- | --- |
| `id`, `name` | The composition whose current document references the asset. |
| `project_id`, `project_name` | Optional, nullable project association. |

> [!WARNING]
> This is advisory usage data. `complete: false` means the scan could not cover everything, such as when more than 200 compositions exist or documents could not be read. Do not treat an incomplete result as proof that an asset is unused.

:::cards
- [Pricing and credits](./billing.html): Read balances, quotes, charges and refunds.
- [Teams and organizations](./organizations.html): Understand shared pools, roles and budgets.
- [Agent Sessions API](./agent-api.html): Follow a conversation and its generated assets.
:::