# Account settings API

> Change the account's name, billing email, sample data, query text and client IP settings, and turn Allow overage on or off.

Source: https://www.apitraffic.io/docs/api-reference/account-settings

The settings an owner or admin changes on the **Account** pages. Send only the fields you want to change.

**Permissions:** an **owner** or **admin**, signed in to the app (a session token). A request made with an API token or by a connected app is refused with `401`, and one from a member with `403`. `billingEmail` and `allowOverage` are the owner's: an admin who sends either is refused with `403`, and an admin's response leaves out `billingEmail`, `allowOverage` and `overageDisabledAt`. The privacy settings and **Allow overage** are also refused from a support session.

## Update account settings

`PATCH https://api.apitraffic.io/v1/account/settings`

### Body parameters

- **name (body, string)**:
  The account's name, up to 125 characters.

- **billingEmail (body, string | null)**:
  Where invoices and payment notices go. Empty or `null` clears it.

- **showSampleData (body, boolean)**:
  Whether the read-only sample bucket is listed for the team. See [Sample data](https://www.apitraffic.io/docs/sample-data).

- **apmStatementTextEnabled (body, boolean)**:
  Whether database spans keep their query text. See [Capture settings](https://www.apitraffic.io/docs/apm/capture-settings).

- **clientIpMode (body, string)**:
  How client IP addresses are kept: `full`, `truncated` or `off`. See [Client IP addresses](https://www.apitraffic.io/docs/account/client-ip-addresses).

- **allowOverage (body, boolean)**:
  Whether usage past an overage-billed allowance is recorded and billed (`true`, the default) or stopped at the allowance until the period resets (`false`). A JSON boolean only. Applies within about a minute. Usage recorded while overage was allowed is still billed; nothing recorded past the allowance while it's off is. Changing it on a plan that doesn't bill overage is accepted and changes nothing. See [Allow overage](https://www.apitraffic.io/docs/account/billing#allow-overage).

### Response

- **sid (string)**: The account identifier.

- **name (string)**: The account's name.

- **billingEmail (string | null)**: The billing email.

- **showSampleData (boolean)**: Whether the sample bucket is listed.

- **apmStatementTextEnabled (boolean)**: Whether query text is stored.

- **clientIpMode (string)**: `full`, `truncated` or `off`.

- **allowOverage (boolean)**: Whether usage past an overage-billed allowance is recorded and billed.

- **overageDisabledAt (string | null)**: When overage was turned off (ISO 8601), or `null` while it's allowed.

```bash
curl -X PATCH "https://api.apitraffic.io/v1/account/settings" \
  -H "Authorization: Bearer your-session-token" \
  -H "Content-Type: application/json" \
  -d '{ "allowOverage": false }'
```

```json
{
  "sid": "acc_2JwnjVUbW5CFL2RfC6CWK0f5h0u",
  "name": "Acme Store",
  "billingEmail": null,
  "showSampleData": true,
  "apmStatementTextEnabled": false,
  "clientIpMode": "full",
  "allowOverage": false,
  "overageDisabledAt": "2026-10-22T10:00:00.000Z"
}
```

Each change is recorded in the [account history](https://www.apitraffic.io/docs/account/activity-log). Turning overage on or off is its own event, `account.overage_toggled`, with `allowed` in its data; see [Webhook event reference](https://www.apitraffic.io/docs/webhooks/reference).

## Read the overage setting

`GET https://api.apitraffic.io/v1/billing/overage`

Where **Allow overage** stands and what it covers. The same object is returned as `overage` by `GET /v1/billing/usage`.

The full object below is returned to the account owner only. Anyone else (admins, members and every API token) gets just `paused` and `periodEnd`: which kinds of usage have stopped being recorded, and when the allowances reset. In the same way, `GET /v1/billing/usage` gives anyone but the owner each usage allowance as a percentage used (`percentUsed`, `unlimited`, `atLimit`, `hardCapped`) and each counted limit as `unlimited` and `atLimit` only, rather than counts and allowances, and the monthly usage endpoints and the plan list answer `403` to anyone but the owner.

- **allowed (boolean)**: Whether usage past an overage-billed allowance is recorded and billed.

- **disabledAt (string | null)**: When it was turned off, or `null` while it's allowed.

- **available (boolean)**: Whether the plan bills overage on anything. When `false`, the setting changes nothing and the app doesn't show it.

- **features (string[])**: The kinds of usage the plan bills overage on, such as `requests` and `mcpCalls`.

- **paused (string[])**: While overage is off, the kinds of usage whose allowance is used up, and so aren't being recorded.

- **periodEnd (string | null)**: When the allowances reset (ISO 8601).

```json
{
  "allowed": false,
  "disabledAt": "2026-10-22T10:00:00.000Z",
  "available": true,
  "features": ["requests", "mcpCalls"],
  "paused": ["requests"],
  "periodEnd": "2026-11-01T00:00:00.000Z"
}
```

## Errors when updating

| Status | When |
|---|---|
| `400` | A field has the wrong type or value, or the body is empty. |
| `401` | Not a signed-in user's session (an API token or a connected app). |
| `403` | The caller is a member, an admin sent `billingEmail` or `allowOverage`, or a support session sent a privacy setting or `allowOverage`. |
| `500` | The setting couldn't be saved. Nothing changed; try again. |