> For the complete documentation index, see [llms.txt](https://docs.telm.ai/telmai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telm.ai/telmai/api-reference/scan-limits-api.md).

# Scan Limits

See how many scans a tenant can start per day, week and month.

Scan limits cap how many scans a tenant can start in a day, a week and a month. Use the Scan Limits API to see a tenant's limits, how many scans it has used in each window, and when each window resets.

## How scan limits work

New tenants start with these limits:

| Window | Default limit |
| ------ | ------------- |
| Day    | 100 scans     |
| Week   | No limit      |
| Month  | 1,000 scans   |

Tenants created before scan limits were introduced have no limits unless Telmai sets them.

Each window is counted in UTC:

| Window  | Period                                               |
| ------- | ---------------------------------------------------- |
| `day`   | One UTC day, starting at 00:00 UTC                   |
| `week`  | One ISO week, starting on Monday at 00:00 UTC        |
| `month` | One calendar month, starting on the 1st at 00:00 UTC |

* Every scan counts, whether it is started from Telmai, through the API, or by a schedule.
* A scan counts against every window that has a limit. When any of them is full, new scans are refused until that window resets.
* A data comparison counts as one scan.
* Retrying an existing scan job doesn't count again, and a scan that fails before it launches gives its slot back.
* Windows without a limit aren't counted.

### When a limit is reached

* **Scans started from Telmai or the API** are refused with `429 Too Many Requests`. This applies to the [Trigger Scan](https://docs.telm.ai/telmai/api-reference/upload-data-api.md) API.
* **Scheduled scans** don't run. The scan job is marked as failed with the same message, which you can see with [Track Scan Job](https://docs.telm.ai/telmai/api-reference/upload-data-api/track-job-status.md).

The error says which limit was reached and when new scans are accepted again. Its `category` is `RATE_LIMITED`, and `retryable` is `false` because the same request fails until the window resets:

```json
{
  "category": "RATE_LIMITED",
  "remediation": "This tenant has used all 100 scans allowed per day. New scans are accepted again at 2026-10-27T00:00 (UTC). To run more scans before then, ask your administrator or support to raise the limit.",
  "retryable": false
}
```

The response also includes `code`, `message` and `errorId` fields. Quote the `errorId` when you contact support.

{% hint style="info" %}
A tenant can't raise its own limits. To change them, contact Telmai support.
{% endhint %}

***

## Get Scan Limits

<mark style="color:blue;">`GET`</mark> `https://{telmai_endpoint}/api/backend/configuration/tenants/{tenant}/scan-limits`

Returns the tenant's limit for each window, the number of scans used in the current window, and when it resets. Only tenant administrators can call this endpoint.

### Path Parameters

| Name                                       | Type   | Description       |
| ------------------------------------------ | ------ | ----------------- |
| `tenant`<mark style="color:red;">\*</mark> | string | Tenant identifier |

### Response Fields

| Field                 | Type            | Description                                                             |
| --------------------- | --------------- | ----------------------------------------------------------------------- |
| `tenant_id`           | string          | Tenant identifier                                                       |
| `windows`             | array           | One entry per window, in the order `day`, `week`, `month`               |
| `windows[].window`    | string          | `day`, `week` or `month`                                                |
| `windows[].limit`     | integer or null | Most scans allowed in the window. `null` means no limit.                |
| `windows[].used`      | integer         | Scans counted in the current window                                     |
| `windows[].resets_at` | string          | When the current window ends and its count starts again (UTC, ISO 8601) |

{% tabs %}
{% tab title="curl" %}

```bash
curl -X 'GET' \
  'https://{telmai_endpoint}/api/backend/configuration/tenants/{tenant}/scan-limits' \
  -H 'accept: application/json' \
  -H 'X-TLM-Key: {api_key}'
```

{% endtab %}
{% endtabs %}

### Responses

{% tabs %}
{% tab title="200" %}

```json
{
  "tenant_id": "your-tenant",
  "windows": [
    { "window": "day", "limit": 100, "used": 37, "resets_at": "2026-10-27T00:00:00Z" },
    { "window": "week", "limit": null, "used": 0, "resets_at": "2026-11-02T00:00:00Z" },
    { "window": "month", "limit": 1000, "used": 412, "resets_at": "2026-11-01T00:00:00Z" }
  ]
}
```

{% endtab %}

{% tab title="401" %}
`Unauthorized`
{% endtab %}

{% tab title="403" %}
`Forbidden` — the caller isn't an administrator of the tenant.
{% endtab %}

{% tab title="404" %}
`Not Found` — the tenant doesn't exist.
{% endtab %}
{% endtabs %}

## Related Documentation

* [Trigger Scan](https://docs.telm.ai/telmai/api-reference/upload-data-api.md)
* [Track Scan Job](https://docs.telm.ai/telmai/api-reference/upload-data-api/track-job-status.md)
* [API Keys](https://docs.telm.ai/telmai/api-reference/authentication-api/api-keys.md)
