---
title: "Get Quick Subscription Status"
method: GET
path: "/api/v1/subscriptions/status"
tags: ["Subscriptions", "Subscriptions"]
---

# Get Quick Subscription Status

`GET /api/v1/subscriptions/status`

## 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/subscriptions/status`
- Auth: none declared

**🚀 QUICK STATUS CHECK - Supports both authenticated and device-based users**

Get lightweight subscription status - perfect for:
- App header (showing plan badge: "Free" or "Premium")
- Dashboard widgets
- Quick checks before user actions
- Displaying remaining scans/gems counters

**Access Methods:**
- **With Token**: Returns user subscription status (authenticated)
- **With X-Device-Id**: Returns device scan status (anonymous)
- **With Both**: Returns user status (token takes priority)
- **With Neither**: Returns 401 error

**Response includes:**
- `plan_type`: "free" or "premium"
- `is_active`: true/false
- `scans_remaining`: number or "unlimited"
- `collection_slots_remaining`: number or "unlimited"

**Example Usage:**
```javascript
// Authenticated user
const status = await fetch('/api/v1/subscriptions/status', {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

// Anonymous user with device tracking
const status = await fetch('/api/v1/subscriptions/status', {
  headers: { 'X-Device-Id': deviceId }
}).then(r => r.json());

// Use for UI
if (status.plan_type === 'free') {
  showUpgradeBanner();
}
if (status.scans_remaining === 0) {
  disableScanButton();
}
```

**Fast & Lightweight** - Only returns essential info for UI state.

## Headers

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

## Response `200`

Successful Response

- QuickSubscriptionStatusResponse: Quick subscription status check - lightweight response for UI state management. Use this API when you need to quickly check: - Is user Free or Premium? - Is subscription active? - How many scans/gems remaining? Perfect for: Headers, dashboards, quick checks before actions
  - `plan_type` string, required: 'free' or 'premium'
  - `is_active` boolean, required: Is subscription active?
  - `is_premium` boolean, required: True if user has active premium subscription, False otherwise
  - `scans_remaining` union, required: 'unlimited' or number
    - string
    - integer
  - `collection_slots_remaining` union, required: 'unlimited' or number (10 - current_count)
    - string
    - integer
  - `scans_limit` integer, nullable: Monthly scan limit (null if unlimited)
  - `collection_limit` integer, nullable: Collection size limit (null if unlimited)
  - `scan_tier` ScanTierQuota: Monthly allowance of a capped paid tier (LNK-SCANTIERS). Null on free plans and on unlimited (pre-tier) Premium.
    - `tier` string, required
    - `scans_used` integer, required
    - `scans_limit` integer, required
    - `scans_remaining` integer, required
    - `resets_at` string, required
    - `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)