---
title: "Check Scan Limit"
method: GET
path: "/api/v1/device/scan/check-limit"
tags: ["Device Management"]
---

# Check Scan Limit

`GET /api/v1/device/scan/check-limit`

## Request

- Base URL: `https://api.gemstoneaiapp.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gemstoneaiapp.com/api/v1/device/scan/check-limit`
- Auth: none declared

GET /api/v1/device/scan/check-limit

Universal scan limit checker for all user types.

Headers:
- Authorization: Bearer token (for authenticated users)
- X-Device-Id: device_instance_id (for anonymous/logged-out users)

Returns detailed limit information with action_required for UI.

Scenarios handled:
- Anonymous user (device not linked)
- Authenticated user (FREE or PREMIUM)
- Logged-out user with FREE plan exhausted
- Logged-out user with PREMIUM plan

## Headers

- `X-Device-Id` integer, nullable
- `authorization` string, nullable

## Response `200`

Successful Response

- ScanLimitCheckResponse: Response for scan limit check API
  - `device_id` string, required
  - `can_scan` boolean, required
  - `scans_remaining` union, required
    - integer
    - string
  - `scans_used` integer, required
  - `scan_limit` integer, nullable
  - `plan_type` string, required
  - `user_status` string, required
  - `message` string, required
  - `linked_to_user` boolean
  - `action_required` string, nullable
  - `tier` string, nullable
  - `resets_at` string, nullable
  - `upgrade_tier` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api.md) · [All operations](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api/revisions/fcb441f55161?raw)