# Logs

## Log Model

### Fields

- **`object`** `"log"`

- **`action`** `string`

   What happened, as a short code such as `sign_in` or `user.mfa_reset`.

- **`success`** `boolean`

   Whether the attempted action succeeded. Failed attempts, like a bad sign-in, are recorded too.

- **`message`** `string | null`

- **`team_id`** `string | null`

   Null on sign-in entries that are not tied to a team.

- **`actor_id`** `string | null`

   Who acted: the user id, or the API key id when a key acted. See `actor_type`. Null when
   Tailglow acted automatically.

- **`actor_type`** `string | null`

   One of `AUTH_SUBJECTS`. Whether a user or an API key acted.

- **`actor_name`** `string | null`

   Display name of the actor as it was WHEN THE ACTION HAPPENED, so a renamed or deleted actor
   still reads correctly. Reads `Tailglow Admin` on entries where a Tailglow operator acted, and
   `Tailglow` on entries Tailglow wrote automatically.

- **`actor_context`** `string | null`

   `app` for a member or API key, `admin` when a Tailglow operator acted on this team, and
   `system` when Tailglow acted automatically, for example when a payment arrived. Decide who
   acted from this field, not from `actor_name`, which members choose themselves.

- **`actor_role_id`** `string | null`

   Role the actor held at the time. Null on entries a customer reads about an operator.

- **`actor_session_id`** `string | null`

   Session the action belongs to, so one actor's run of changes can be grouped.

- **`resource_type`** `string | null`

   What the entry is about: the user who signed in, or the row that changed.

- **`resource_id`** `string | null`

   Identifier of the resource named by `resource_type`.

- **`ip_address`** `string | null`

- **`device`** `string | null`

   Readable device summary parsed from the user agent, for example `Chrome 126 on Mac OS`.

- **`user_agent`** `string | null`

- **`created_at`** [`ISODateString`](/api/logs#iso-date-string)

- **`type`** [`LogType`](/api/logs#log-type)

   Which kind of entry this is: `auth` for sign-in activity, `audit` for changes to resources,
   `billing` for changes to the team's billing.

- **`details`** [`AuthLogDetails`](/api/logs#auth-details-model) | [`AuditLogDetails`](/api/logs#audit-details-model) | [`BillingLogDetails`](/api/logs#billing-details-model)

   Extra context whose shape follows `type`: `AuthLogDetails` for sign-ins, `AuditLogDetails` for
   changes, `BillingLogDetails` for billing.

### Referenced Types

#### ISODateString

`ISODateString`

An ISO 8601 date-time string returned at the JSON API boundary.

#### LogType

`"auth" | "admin_auth" | "audit" | "billing"`

#### BillingPlan

`"pro_v1" | "enterprise_v1"`

## Auth Log Details Model

### Fields

- **`email`** `string`

   The email address the sign-in was attempted with.

### Referenced Types

#### ISODateString

`ISODateString`

An ISO 8601 date-time string returned at the JSON API boundary.

## Audit Log Details Model

### Fields

- **`changed_fields`** `string[]`

   The fields the request changed, sorted and de-duplicated.

- **`endpoint`** `string | null`

   The API endpoint the change came through.

- **`request_client`** `string | null`

   Which surface made the request: the API directly, the dashboard, the admin portal, or the AI
   assistant.

- **`client_version`** `string | null`

   Version of the client that made the request, when it reported one.

- **`ai_chat_id`** `string | null`

   Set when the AI assistant made the change; identifies the chat it happened in.

- **`[key: string]`** `unknown`

   Any additional key recorded with the entry.

### Referenced Types

#### ISODateString

`ISODateString`

An ISO 8601 date-time string returned at the JSON API boundary.

## Billing Log Details Model

### Fields

- **`amount_cents`** `number`

   Amount in cents, such as an invoice total or a failed payment.

- **`stripe_invoice_id`** `string`

   Stripe's id for the invoice, as shown on the invoice list.

- **`period_start_at`** [`ISODateString`](/api/logs#iso-date-string)

   First moment of the billing month the entry is about.

- **`plan_from`** [`BillingPlan`](/api/logs#billing-plan)

- **`plan_to`** [`BillingPlan`](/api/logs#billing-plan)

- **`payment_method_brand`** `string`

- **`payment_method_last4`** `string`

- **`discount_id`** `string`

- **`discount_percent`** `number`

- **`discount_amount_cents`** `number`

- **`line_item_type`** `string`

   The invoice line a discount applies to, such as `compute` or `storage`.

- **`available_ai_tokens_before`** `number`

   Tailglow AI tokens available to the team before the entry's change.

- **`available_ai_tokens_after`** `number`

   Tailglow AI tokens available to the team after the entry's change.

- **`trial_ends_at`** [`ISODateString`](/api/logs#iso-date-string)

   When the free trial ends after the entry's change.

- **`days`** `number`

   Days the free trial was extended by.

- **`server_hours`** `number`

   Server-hours of credit the entry added.

- **`has_payment_method`** `boolean`

   For a trial that ended: whether a payment method was on file, so its servers kept running.

- **`invoice_id`** `string`

   For a delinquency change: the invoice that caused it, or whose payment cleared it.

### Referenced Types

#### ISODateString

`ISODateString`

An ISO 8601 date-time string returned at the JSON API boundary.

#### BillingPlan

`"pro_v1" | "enterprise_v1"`

## List Logs

### Endpoint

Retrieve activity logs available to the current authorization.

```http
GET /v1/logs
```

### Query Parameters

- **`order_by`** `string`
  Field used to order the logs. Optional. Defaults to `"created_at"`. Allowed values: `"created_at"`.

- **`start_at`** [`ISODateString`](/api/logs#iso-date-string)
  Earliest log date and time to return. Optional.

- **`end_at`** [`ISODateString`](/api/logs#iso-date-string)
  Latest log date and time to return. Optional.

- **`team_id`** `string`
  Filter by team ID. Optional.

- **`user_id`** `string`
  Filter by user ID. Optional.

- **`type`** [`LogType`](/api/logs#log-type)
  Filter by log type. Optional.

- **`limit`** `number`
  Maximum number of items to return. Optional. Defaults to `25`. Minimum: `1`. Maximum: `200`.

- **`after`** `string`
  Cursor from `pagination.next_cursor` of a previous response. Returns the resources after that page. Optional.

- **`before`** `string`
  Cursor from `pagination.prev_cursor` of a previous response. Returns the resources before that page. Optional.

- **`sort`** `string`
  Sort direction for the result set. Optional. Defaults to `"desc"`. Allowed values: `"asc"`, `"desc"`.

### Response

```ts
{
  message: string;
  data: Log[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}
```

### Comments

- You can retrieve your own authentication logs without `logs:read`. Billing logs require `billing:read`; all other log reads require `logs:read`.
- Without `type`, the list includes every type you can read. `admin_auth` logs exist only on Tailglow's own admin team.
- `after` and `before` are mutually exclusive.