Usage alerts

Find out before an app runs out of room. When an app reaches a share of one of its plan's limits, Fileboy emails you, shows a banner in the dashboard and sends a

usage.threshold_reached

webhook. Every app has alerts at 80% and 100% from the start, and you can change them.

What is watched

Limits

files

How many files the app has, counted the way the upload limit counts them (resized copies don't count). This is a hard limit: at 100% new uploads are refused.

videos

How many videos the app has, against the plan's video allowance.

storage

Every byte the app stores: originals, resized copies, video renditions, posters and captions, against the plan's storage allowance.

A limit the app's plan doesn't set is never alerted on. Data transfer is not measured per app yet, so it can't send alerts. See pricing for each plan's limits.

When alerts are sent

Fileboy checks every app's usage every few minutes. A threshold is reached when usage is at least that share of the limit, so 800 of 1,000 files reaches 80%.

Each threshold is sent at most once a month for each limit, however often usage goes over and back under it.
Months are calendar months in UTC. On the 1st every threshold can fire again, so an app still over 80% gets one reminder at the start of the month.
If usage jumps past several thresholds between two checks, say from 40% to 95% with alerts at 50, 80 and 90, only the 90% alert is sent. The lower ones are marked as reached so they don't follow later.
What has been sent is stored, so restarts and repeated checks never send an alert twice.

Where they go

Channels

Email

To everyone on the app, and up to 10 more addresses. A failed email is retried for up to a day.

Dashboard banner

Across the top of every page of the app while it is over a threshold. Dismissing it hides that threshold until the next one or the next month.

Webhook

A usage.threshold_reached event to every endpoint that receives it or every event. Signed and retried like every other event.

usage.threshold_reached

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "id": "b7c2d9e4-1f3a-5b6c-8d7e-9f0a1b2c3d4e",
  "type": "usage.threshold_reached",
  "created": "2026-11-14T10:05:00Z",
  "appId": "0b9e3b4c-5b52-4b5e-9d2e-1b0c2c8a4f77",
  "resource": {
    "metric": "files",
    "threshold": 80,
    "used": 812,
    "limit": 1000,
    "unit": "count",
    "percent": 81.2,
    "period": { "start": "2026-11-01T00:00:00Z", "end": "2026-12-01T00:00:00Z" },
    "plan": "Free"
  }
}

The resource fields are listed in the webhooks reference.

Settings

Open your app in the dashboard and go to Usage alerts. You can:

turn alerts off for the app,
choose up to five thresholds from 1% to 100%, like 50, 80, 90 and 100,
choose which of files, videos and storage are watched,
choose who is emailed, and whether the webhook is sent,
preview the email and the webhook payload, and send a test of either. Tests use the app's real usage, say they are tests (
```
"test": true
```
in the webhook), and don't count as the month's alert.

The page also lists the alerts the app has had.

From the API

GET /usage/alerts

returns the settings, the current month and the alerts recorded in it.

PATCH /usage/alerts

changes only the fields you send, and

metrics

only changes the limits it names. Both need your private key, like the rest of the management API.

Read

1
curl 'https://api.fileboy.io/usage/alerts' -H 'Authorization: token 0000000....'

Change

1
curl -X PATCH 'https://api.fileboy.io/usage/alerts' -H 'Authorization: token 0000000....' -H 'Content-Type: application/json' -d '{ "thresholds": [50, 80, 90, 100], "recipients": ["ops@example.com"], "metrics": { "videos": false } }'

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "data": {
    "settings": {
      "enabled": true,
      "thresholds": [50, 80, 90, 100],
      "metrics": { "files": true, "videos": false, "storage": true },
      "emailMembers": true,
      "recipients": ["ops@example.com"],
      "webhook": true
    },
    "period": {
      "key": "2026-11",
      "start": "2026-11-01T00:00:00Z",
      "end": "2026-12-01T00:00:00Z"
    },
    "alerts": [
      {
        "id": "8d2b4f0e-5a1c-5e3b-9f7d-2c4e6a8b0d13",
        "metric": "files",
        "threshold": 80,
        "used": 812,
        "limit": 1000,
        "notified": true,
        "email": "sent",
        "createdAt": "2026-11-14T10:05:00Z"
      }
    ]
  }
}

A threshold is a whole number from 1 to 100, with at most five. Recipients must be email addresses, at most 10. Anything else is a

400 validation_error

, an unknown field is

invalid_json

and an empty body is

empty_update

Usage alerts

What is watchedWhen alerts are sentWhere they goSettingsFrom the API

Getting Started

Uploads

Delivery

Video

Libraries

API Reference

Usage alerts

What is watched

When alerts are sent

Where they go

Settings

From the API

Usage alerts