# AGENT_USAGE view


> Query AI Unit usage for Agent Harness runs across your MotherDuck organization.

**Requires permission:** View query history — included by default in the Admin and Builder preset roles. A custom role qualifies when it inherits a role that includes the permission. Available on the Business plan. AGENT_USAGE uses the same permission as QUERY_HISTORY. Business trials are included. See [Roles and access control](/concepts/security-and-access/roles-and-access-control/#what-each-role-can-do).

The `MD_INFORMATION_SCHEMA.AGENT_USAGE` view shows Agent Harness AI consumption across your organization. Each row represents one run, identified by `session_id` and `run_seq`. In Agent chat, a run corresponds to one chat turn.

The view includes runs initiated by all users in the organization. It does not apply per-user row-level filtering.

## Schema

| Column | Data type | Description |
| --- | --- | --- |
| `run_finished_ts` | TIMESTAMP WITH TIME ZONE | Time when the agent run finished. |
| `user_id` | UUID | ID of the user who initiated the run. |
| `user_name` | VARCHAR | Name of the user who initiated the run. |
| `surface` | VARCHAR | Product surface that generated the usage. Agent chat rows contain `chat`. |
| `session_id` | UUID | Durable session ID. For Agent chat, this is the ID in the `/chats/<session_id>` URL. |
| `run_seq` | BIGINT | Sequence number of the run within the session. Each Agent chat turn corresponds to one run. |
| `ai_units` | DOUBLE | Model usage for this run, in [AI Units](/about-motherduck/billing/pricing/#agent-chat-pricing). |

## Examples

### Query recent agent chat usage

```sql
SELECT
    run_finished_ts,
    user_name,
    session_id,
    run_seq,
    ai_units
FROM md_information_schema.agent_usage
WHERE surface = 'chat'
ORDER BY run_finished_ts DESC;
```

### Summarize agent chat usage by user

```sql
SELECT
    user_name,
    SUM(ai_units) AS total_ai_units
FROM md_information_schema.agent_usage
WHERE surface = 'chat'
GROUP BY user_name
ORDER BY total_ai_units DESC;
```

## See also

- [Agent chat](/key-tasks/ai-and-motherduck/ai-in-the-ui/agent-chat/) — Work with MotherDuck in plain language.
- [Monitoring usage and costs](/about-motherduck/billing/monitoring-usage/) — Monitor compute and storage consumption.


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Fmotherduck-sql-reference%2Fmd_information_schema%2Fagent_usage%2F&page_title=AGENT_USAGE%20view&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.