# ApiRequest

> The API request log: every write and every failed request made with your keys and sessions (successful reads aren't logged), newest first.

```python
page = noclick.ApiRequest.list_page(method="POST", status="4xx", key="nk_live_ab12")
```

## noclick.ApiRequest

```python
class ApiRequest
```

One logged request. `actor` is `key`, `session` or `owner`;
`route` is the template (`/v1/agents/{agent_id}/messages`).

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `str` |  |
| `actor` | `str | None` |  |
| `key_id` | `str | None` |  |
| `user_id` | `str | None` |  |
| `session_id` | `str | None` |  |
| `method` | `str` |  |
| `route` | `str` |  |
| `path_params` | `dict[str, Any]` |  |
| `status` | `int | None` |  |
| `error_type` | `str | None` |  |
| `duration_ms` | `int | None` |  |
| `idempotency_replayed` | `bool` |  |
| `operation_id` | `str | None` |  |
| `request_id` | `str | None` |  |
| `created_at` | `Any` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

### ApiRequest.list

```python
noclick.ApiRequest.list(
    *, method=None, status=None, error_type=None, key=None, route=None, since=None,
    until=None, limit=None, user_filter=None, user=..., client=None
) -> list[ApiRequest]
```

Every matching request (or the first `limit`). `status` is a class
(`"4xx"`) or a code; `key` a key id or prefix.

Parameters:

- `method` (`str | None`, default `None`)
- `status` (`str | int | None`, default `None`)
- `error_type` (`str | None`, default `None`)
- `key` (`str | None`, default `None`)
- `route` (`str | None`, default `None`)
- `since` (`Any`, default `None`)
- `until` (`Any`, default `None`)
- `limit` (`int | None`, default `None`): Return at most this many.
- `user_filter` (`Any`, default `None`): Which users a read covers: `noclick.ALL_USERS`, `noclick.NO_USER`, a `User`, or your id for one. It filters without acting as that user.
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `list[ApiRequest]` Every matching request, newest first, fetched page by page.

Usage:

See the writes one key had refused:

```python
for request in noclick.ApiRequest.list(method="POST", status="4xx", key="nk_live_ab12", limit=50):
    print(request.created_at, request.route, request.status, request.error_type)
```

Or every request a spend cap turned away:

```python
capped = noclick.ApiRequest.list(error_type="spend_cap_exceeded", limit=20)
```

`route` takes the template, and `status` a single code:

```python
limited = noclick.ApiRequest.list(route="/v1/agents/{agent_id}/messages", status=429)
```

### ApiRequest.list_page

```python
noclick.ApiRequest.list_page(
    *, cursor=None, limit=None, method=None, status=None, error_type=None, key=None,
    route=None, since=None, until=None, user_filter=None, user=..., client=None
) -> Page
```

One page of matching requests; pass `next_cursor` back as `cursor`.

Parameters:

- `cursor` (`str | None`, default `None`): The `next_cursor` of the page before; omit it for the first page.
- `limit` (`int | None`, default `None`): Return at most this many.
- `method` (`str | None`, default `None`)
- `status` (`str | int | None`, default `None`)
- `error_type` (`str | None`, default `None`)
- `key` (`str | None`, default `None`)
- `route` (`str | None`, default `None`)
- `since` (`Any`, default `None`)
- `until` (`Any`, default `None`)
- `user_filter` (`Any`, default `None`): Which users a read covers: `noclick.ALL_USERS`, `noclick.NO_USER`, a `User`, or your id for one. It filters without acting as that user.
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `Page` A page whose `data` holds up to `limit` requests (at most 200) and whose `next_cursor`
is `None` on the last page.

Usage:

```python
page = noclick.ApiRequest.list_page(status="5xx", limit=200)
while True:
    for request in page.data:
        print(request.request_id, request.route, request.status)
    if page.next_cursor is None:
        break
    page = noclick.ApiRequest.list_page(status="5xx", limit=200, cursor=page.next_cursor)
```
