---
title: "List Logs"
method: GET
path: "/logs"
tags: ["Logs"]
---

# List Logs

`GET /logs`

Lists log entries of the requested `type` for the authenticated account.

- `change`: audit entries recording each insert, update, or delete event
  against an account-scoped object, most recent first.
- `session`: one entry per Client, Gateway, or Portal session created,
  most recent first.
- `flow`: one entry per network flow reported by Clients and Gateways,
  most recently started first.
- `api_request`: one entry per authenticated REST API request, most
  recent first.

The `begin` and `end` query parameters bound the time window. For
`change`, `session`, and `api_request`, entries match when their
`timestamp` falls inside the window; for `flow`, entries match when
the flow was active at any point inside the window, i.e. when
`[flow_start, flow_end)` overlaps it. Both must be RFC 3339 (ISO
8601) timestamps, for example `2026-05-26T00:00:00Z`; values with a
non-UTC offset are accepted and converted to UTC. When omitted,
`begin` defaults to 90 days before the current time and `end`
defaults to the current time. `begin` must be less than or equal to
`end`.

Results can be further narrowed by `actor_id` (every type) or
`actor_email` (`change`, `session`, and `flow`), which matches the
email recorded when the entry was created. API requests are made by
API clients, which have no email, so `actor_email` is not supported
for `api_request`.

Use the `next_page` cursor returned in `metadata` to fetch the
following page of results.

## Query parameters

- `type` string, required
- `limit` integer
- `page_cursor` string
- `begin` string
- `end` string
- `actor_id` string
- `actor_email` string

## Response `200`

Logs Response

- LogsResponse — Response schema for a page of Log entries. Entries are returned most recent first. Each page contains at most 100 entries (50 by default); use the `metadata.next_page` cursor to fetch the following page.
  - `data` Log[] — Log entries for the requested window.
    - union — A single Log entry. The `type` field identifies the log stream the entry belongs to, which is also encoded in the first character of its `log_id` (`c` change, `5` session, `f` flow, `a` api_request).
      - ChangeLog — A single entry from the account audit log. Each entry records one create, update, or delete event against an account-scoped object.
        - `after` object, nullable — The state of the object after the change. `null` for `delete` events. Sensitive fields such as tokens, secrets, and password hashes are replaced with the literal string `"[redacted]"`.
        - `before` object, nullable — The state of the object before the change. `null` for `insert` events. Sensitive fields such as tokens, secrets, and password hashes are replaced with the literal string `"[redacted]"`.
        - `log_id` string, required — Opaque identifier for the audit log entry. A 24-character lowercase hexadecimal string starting with `c`, lexicographically sortable within an account and aligned with the order changes were committed.
        - `object` string, required — The kind of object that was changed.
        - `operation` 'insert' | 'update' | 'delete', required — The kind of change that was applied.
        - `subject` Subject, nullable — Identifies the actor and request context that initiated an action. Used to describe the principal behind an audit log entry, an authorized flow, or any other event surfaced through the API. May be `null` when the action originated outside the context of a Firezone session.
          - `actor_email` string, nullable — Email address of the actor, if any.
          - `actor_id` string, uuid — Identifier of the actor that initiated the action.
          - `actor_name` string — Display name of the actor.
          - `actor_type` 'account_user' | 'account_admin_user' | 'service_account' | 'api_client' — Type of the actor.
          - `auth_provider_id` string, uuid, nullable — Identifier of the authentication provider that authenticated the actor.
          - `ip` string, nullable — IP address the action originated from.
          - `ip_city` string, nullable — Geo-located city for `ip`, if known.
          - `ip_lat` number, nullable — Geo-located latitude for `ip`, if known.
          - `ip_lon` number, nullable — Geo-located longitude for `ip`, if known.
          - `ip_region` string, nullable — Geo-located region for `ip`, if known.
          - `user_agent` string, nullable — User agent of the client that initiated the action.
        - `timestamp` string, date-time, required — RFC 3339 timestamp identifying when the change was committed.
        - `type` 'change', required
      - SessionLog — A single Session Log entry, recording one Client, Gateway, or Portal session that was created, along with the auth context it was created with.
        - `context` 'client' | 'gateway' | 'portal', required — The kind of session that was created.
        - `log_id` string, required — Opaque identifier for the Session Log entry. A 24-character lowercase hexadecimal string starting with `5`.
        - `subject` Subject, nullable, required — Identifies the actor and request context that initiated an action. Used to describe the principal behind an audit log entry, an authorized flow, or any other event surfaced through the API. May be `null` when the action originated outside the context of a Firezone session.
          - `actor_email` string, nullable — Email address of the actor, if any.
          - `actor_id` string, uuid — Identifier of the actor that initiated the action.
          - `actor_name` string — Display name of the actor.
          - `actor_type` 'account_user' | 'account_admin_user' | 'service_account' | 'api_client' — Type of the actor.
          - `auth_provider_id` string, uuid, nullable — Identifier of the authentication provider that authenticated the actor.
          - `ip` string, nullable — IP address the action originated from.
          - `ip_city` string, nullable — Geo-located city for `ip`, if known.
          - `ip_lat` number, nullable — Geo-located latitude for `ip`, if known.
          - `ip_lon` number, nullable — Geo-located longitude for `ip`, if known.
          - `ip_region` string, nullable — Geo-located region for `ip`, if known.
          - `user_agent` string, nullable — User agent of the client that initiated the action.
        - `timestamp` string, date-time, required — RFC 3339 timestamp identifying when the session was created.
        - `type` 'session', required
      - FlowLog — A single Flow Log entry, recording one network flow as accounted by one of its two endpoints. Both endpoints of a flow report it independently, so a flow yields up to two entries that differ only in `role` and in the counters each side observed. Every other field is oriented from the initiator regardless of which side reported the entry: `inner_src_*` is always the initiator, `inner_dst_*` always the responder, and `tx_*` always counts initiator-to-responder traffic. `outers` records each outer network path in the order it was observed. Comparing the two entries of a flow is how reported traffic is cross-checked.
        - `log_id` string, required — Opaque identifier for the Flow Log entry. A 24-character lowercase hexadecimal string starting with `f`.
        - `initiator_device_id` string, required — ID of the Client that opened the flow. Always a Client.
        - `last_packet` string, date-time, nullable, required — When the last packet was seen. Null while the flow is open.
        - `inner_dst_ip` string, required — Tunnel IP of the responder, on both entries of the flow.
        - `initiator_auth_provider_id` string, nullable — ID of the Auth Provider the initiating Client authenticated with.
        - `initiator_device_uuid` string, nullable — Device UUID reported by the initiating Client.
        - `flow_end` string, date-time, nullable, required — RFC 3339 timestamp of when the flow ended. Null while the flow is open.
        - `initiator_device_identifier_for_vendor` string, nullable — Vendor identifier reported by the initiating Client.
        - `policy_authorization_id` string, required — ID of the Policy Authorization that permitted the flow.
        - `tx_bytes` integer, nullable, required — Bytes sent initiator-to-responder, as counted by the reporting side. Null while the flow is open.
        - `initiator_client_version` string, nullable — Firezone Client version reported by the initiating Client.
        - `type` 'flow', required
        - `rx_packets` integer, nullable, required — Packets sent responder-to-initiator, as counted by the reporting side. Null while the flow is open.
        - `initiator_device_os_name` string, nullable — Operating system reported by the initiating Client.
        - `timestamp` string, date-time, required — RFC 3339 timestamp identifying when the flow was ingested.
        - `role` 'initiator' | 'responder', required — Which of the two endpoints reported this entry: `initiator` means `initiator_device_id` wrote it, `responder` means `responder_device_id` did. Gateways always report `responder`; Clients report either role.
        - `tx_packets` integer, nullable, required — Packets sent initiator-to-responder, as counted by the reporting side. Null while the flow is open.
        - `inner_dst_port` integer, required
        - `initiator_device_firebase_installation_id` string, nullable — Firebase installation ID reported by the initiating Client.
        - `inner_src_ip` string, required — Tunnel IP of the initiator, on both entries of the flow.
        - `responder_device_id` string, required — ID of the device the flow was opened to: the Gateway serving the Resource, or the receiving Client for device-to-device flows.
        - `initiator_actor_email` string, nullable
        - `protocol` 'tcp' | 'udp', required — Transport protocol of the flow.
        - `authorization_expires_at` string, date-time, required — When the Policy Authorization expires.
        - `outers` object[], nullable, required — Outer network paths in observation order. Null while the flow is open; the close report replaces it with the complete array. Source IP and port must either both be populated or both be absent/null. The two entries of a flow can disagree whenever NAT or a relay sits between the peers.
          - `dst_ip` string, required
          - `dst_port` integer, required
          - `path_activated_at` string, date-time, nullable — RFC 3339 timestamp of when the path was selected.
          - `src_ip` string, nullable
          - `src_port` integer, nullable
        - `resource_id` string, required — ID of the Resource accessed.
        - `inner_src_port` integer, required
        - `rx_bytes` integer, nullable, required — Bytes sent responder-to-initiator, as counted by the reporting side. Null while the flow is open.
        - `authorized_at` string, date-time, required — When access to the Resource was authorized.
        - `flow_start` string, date-time, required — RFC 3339 timestamp of when the flow began. The `begin`/`end` window matches flows whose [`flow_start`, `flow_end`) range overlaps it.
        - `initiator_device_os_version` string, nullable — Operating system version reported by the initiating Client.
        - `inner_domain` string, nullable — Domain name for flows to DNS Resources.
        - `initiator_actor_id` string, nullable — ID of the Actor who opened the flow. This is always the initiating Client's Actor. A Gateway has no Actor, and for device-to-device flows the receiving Client's own Actor is not recorded here.
        - `initiator_actor_name` string, nullable
        - `resource_address` string, nullable, required — Resource address, when the Resource type has one.
        - `initiator_device_serial` string, nullable — Device serial number reported by the initiating Client.
        - `resource_name` string, required
        - `policy_id` string, required — ID of the Policy that permitted the flow.
      - APIRequestLog — A single API Request Log entry, recording one authenticated REST API request.
        - `actor_id` string, required — ID of the API Client actor.
        - `api_token_id` string, required — ID of the API token used.
        - `content_length` integer, nullable — Value of the Content-Length request header, when present.
        - `ip` string, required
        - `ip_city` string, nullable
        - `ip_lat` number, nullable
        - `ip_lon` number, nullable
        - `ip_region` string, nullable
        - `log_id` string, required — Opaque identifier for the API Request Log entry. A 24-character lowercase hexadecimal string starting with `a`.
        - `method` string, required — HTTP request method.
        - `path` string, required — HTTP request path.
        - `request_id` string, required — Request ID assigned by the server, for correlating with server logs.
        - `timestamp` string, date-time, required — RFC 3339 timestamp identifying when the request was received.
        - `type` 'api_request', required
        - `user_agent` string, nullable
  - `metadata` object — Pagination metadata

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `429` — Too Many Requests

---

[API](https://skmtc.dev/firezone/apis/firezone-api.md) · [All operations](https://skmtc.dev/firezone/apis/firezone-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/firezone/firezone-api/revisions/110de2cb2283/schema)