---
title: "List license instances"
method: GET
path: "/api/v1/licenses/instances"
tags: ["internal"]
---

# List license instances

`GET /api/v1/licenses/instances`

## Request

- Base URL: `https://app.scanopy.net`
- URL: `https://app.scanopy.net/api/v1/licenses/instances`
- Auth: one of:
  - API key in header `Authorization`
  - API key in cookie `session_id`

The server instances running this organization's license key.
An instance counts against the limit while it has checked in within the
last week.

## Response `200`

The organization's server instances

- ApiResponseLicenseInstancesResponse: Envelope for a successful response. Failures are sent with a non-2xx status and an `ApiErrorResponse` body instead.
  - `data` object: The server instances an organization's online key is running on.
    - `instances` LicenseInstanceSummary[], required: Every instance that has checked in, most recent first, including ones silent long enough to no longer count.
      - `active` boolean, required: Whether the instance counts against the limit: it checked in within the last week.
      - `instance` LicenseInstance, required: A server instance that has checked in with an organization's online key, as the cloud records it.
        - `active_since` string, date-time, required: When the instance last started counting in its class: its first check-in, its first after a silence, or a change of class. Slots go to active instances in this order, so a server coming back never displaces one that held the slot meanwhile.
        - `first_seen_at` string, date-time, required: First check-in.
        - `instance_id` string, uuid, nullable: The id the server's database holds. `None` on the one row shared by servers too old to send it.
        - `last_seen_at` string, date-time, required: Latest check-in.
        - `last_seen_ip` string, nullable: Source address the cloud observed on the latest check-in. The server never sends an address; behind NAT several servers share one.
        - `non_production` boolean, nullable: Whether the latest check-in came from a server started with `SCANOPY_NON_PRODUCTION`. Production and non-production servers take slots from separate limits. `None` when that check-in came from a server older than the setting: it counts as production and is never refused.
        - `organization_id` string, uuid, required: Organization whose online key the instance checks in with.
        - `server_version` string, nullable: Version the latest check-in reported, as semver text.
        - `created_at` string, date-time, required: When the cloud created the record.
        - `id` string, uuid, required: Id of the cloud's record for this instance.
        - `updated_at` string, date-time, required: When the cloud last changed the record.
      - `refused` boolean, required: Whether the instance is past its class's limit and refused its entitlement, so it is read-only.
    - `usage` InstanceUsage, required: Server instances an online key has checked in from within the last `LICENSE_SILENCE_THRESHOLD_DAYS`, and how many the organization's licence covers (`None` when the plan has no cap), for production and non-production servers. A server past its class's limit is refused an entitlement.
      - `active` integer, required: Production servers.
      - `limit` integer, nullable: Production servers the key covers. `None` is no cap.
      - `non_production_active` integer, required: Servers started with `SCANOPY_NON_PRODUCTION`. Absent from clouds older than the setting.
      - `non_production_limit` integer, nullable, required: Non-production servers the key covers. `None` is no cap.
  - `error` string, nullable: Not sent on a successful response. Failure messages arrive in an `ApiErrorResponse`.
  - `meta` ApiMeta, required: API metadata included in all responses
    - `api_version` integer, required: API version (integer, increments on breaking changes)
    - `server_version` string, required: Server version (semver)
  - `success` boolean, required: Always `true` on a successful response.

## Other responses

- `403`: Not an owner

## Changes

- **2026-10-26** `c9d9d46d1ae8`: 1 info
  - api tag `billing` removed
- **2026-10-14** `29b77b6b0404`: 1 breaking, 5 info
  - removed the required property `data/instances/items/holds_slot` from the response with the `200` status
  - added the optional property `data/instances/items/instance/allOf[#/components/schemas/LicenseInstanceBase]/non_production` to the response with the `200` status
  - added the required property `data/instances/items/instance/allOf[#/components/schemas/LicenseInstanceBase]/active_since` to the response with the `200` status
  - added the required property `data/instances/items/refused` to the response with the `200` status
  - …2 more
- **2026-10-14** `6b3ab454fd28`: 1 info
  - added the required property `data/instances/items/holds_slot` to the response with the `200` status
- **2026-10-14** `a68a9285f72d`: 2 breaking
  - the response property `data/usage/limit` became nullable for the status `200`
  - the response property `data/usage/limit` became optional for the status `200`
- **2026-10-14** `9461f5876538`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/scanopy/apis/scanopy-api/changes/api/v1/licenses/instances/get.md)

---

[API](https://skmtc.dev/scanopy/apis/scanopy-api.md) - [All operations](https://skmtc.dev/scanopy/apis/scanopy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scanopy/apis/scanopy-api/revisions/966ba786bdb5?raw)