# WebUsageRecord

One metered call an agent's web tools made: a page of search results, a page read, a direct download, or an image description. Recorded once, when the call succeeds; failed attempts are not charged and are not recorded. These calls also count towards a run's usage.

**Kind:** an object, used in responses.

## Fields

Every field is present in a response; empty ones are `null`.

| Field | Type | Description |
|---|---|---|
| `kind` | [`WebUsageKind`](https://docs.maitento.com/reference/types/web-usage-kind.md) | What the call was for. |
| `processType` | [`ProcessType`](https://docs.maitento.com/reference/types/process-type.md) | The kind of run whose agent made the call. |
| `processId` | `uuid` | The run (an interaction or code pipeline run) whose agent made the call. |
| `agentName` | `string \| null` | The participant (interaction) or pipeline agent that made the call. |
| `agentId` | `uuid \| null` | The agent definition that made the call, when the caller is an interaction agent. |
| `provider` | `string` | Who served it: `WebScrapingAi`, `Direct`, or the image model's provider. |
| `tier` | [`WebProxyTier`](https://docs.maitento.com/reference/types/web-proxy-tier.md)`\| null` | Pages: the proxy tier that succeeded. |
| `credits` | `integer` | The web provider's own units (credits) charged for the call; 0 where it charges none. |
| `bytes` | `integer` | Bytes received (downloads and pages), or the image's size (descriptions). |
| `host` | `string \| null` | The host the call was about. |
| `target` | `string \| null` | What was asked, for the run's audit trail: a page's or file's URL without its query and fragment (they can carry secrets), or a search's query (at most 200 characters). |
| `page` | `integer \| null` | Searches: the results page that was read. |
| `durationMs` | `integer` | How long the call took, in milliseconds. |
| `fileId` | `uuid \| null` | The file the call produced, in the run's web-download partition. |
| `model` | `string \| null` | Image descriptions: the model that described the image. |
| `inputTokens` | `integer` | Image descriptions: the input tokens the model used. 0 for other calls. |
| `outputTokens` | `integer` | Image descriptions: the output tokens the model used. 0 for other calls. |
| `date` | `datetime` | When the call was made (UTC). |
| `expireAt` | `datetime` | When the record is removed (UTC). |
| `tenantId` | `uuid` | The id of the tenant it belongs to. |
| `id` | `uuid` | The unique id. Use it in `by-id` routes and wherever another object refers to this one. |
| `dateCreated` | `datetime` | When it was created, in UTC. |
| `dateUpdated` | `datetime` | When it was last changed, in UTC. |

## Example

```json
{
  "kind": "Search",
  "processType": "App",
  "processId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "agentName": "...",
  "agentId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "provider": "...",
  "tier": "Datacenter",
  "credits": 0,
  "bytes": 0,
  "host": "...",
  "target": "...",
  "page": 0,
  "durationMs": 0,
  "fileId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "model": "...",
  "inputTokens": 0,
  "outputTokens": 0,
  "date": "2026-10-26T12:00:00.0000000Z",
  "expireAt": "2026-10-26T12:00:00.0000000Z",
  "tenantId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "dateCreated": "2026-10-26T12:00:00.0000000Z",
  "dateUpdated": "2026-10-26T12:00:00.0000000Z"
}
```

## Where it's used

- [`runs.webUsage`](https://docs.maitento.com/reference/api/runs.md) (`GET /web/usage/by-process/{processId}`)