USuseautumn
entities

POST /v1/entities.list

Lists entities across the organization with pagination and optional filters.

Use this to page through entities globally, including filtering by plans inherited from parent customers or attached directly to entities.

Request

Headers

x-api-versionstring required

Request body

start_cursorstring

Opaque pagination cursor. Empty string (default) requests the first page; use next_cursor from a prior response for subsequent pages.

limitinteger

Number of items to return. Default 50, hard ceiling 5000.

subscription_status'active' | 'scheduled'

Filter customer products used for entity hydration and plan matching. Defaults to active and scheduled.

searchstring

Search entities by id or name.

processorsstring[]

Filter by parent customer processor type (stripe, revenuecat, vercel).

customer_idstring

Restrict the response to entities owned by this customer id. Use to bulk-fetch all entities for one customer in a single paginated call instead of iterating entities.get.

Example request

{
  "start_cursor": "",
  "limit": 10
}

Response

OK

next_cursorstring nullable required

Opaque cursor for the next page. Null when there are no more results.

Example response

{
  "list": [
    {
      "id": "seat_42",
      "name": "Seat 42",
      "customer_id": "cus_123",
      "feature_id": "seats",
      "created_at": 1771409161016,
      "env": "sandbox",
      "subscriptions": [
        {
          "plan_id": "pro_plan",
          "auto_enable": true,
          "add_on": false,
          "status": "active",
          "past_due": false,
          "canceled_at": null,
          "expires_at": null,
          "trial_ends_at": null,
          "started_at": 1771431921437,
          "current_period_start": 1771431921437,
          "current_period_end": 1771999921437,
          "quantity": 1
        }
      ],
      "purchases": [],
      "balances": {
        "messages": {
          "feature_id": "messages",
          "granted": 100,
          "remaining": 72,
          "usage": 28,
          "unlimited": false,
          "overage_allowed": false,
          "max_purchase": null,
          "next_reset_at": 1773851121437,
          "breakdown": [
            {
              "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
              "plan_id": "pro_plan",
              "included_grant": 100,
              "prepaid_grant": 0,
              "remaining": 72,
              "usage": 28,
              "unlimited": false,
              "reset": {
                "interval": "month",
                "resets_at": 1773851121437
              },
              "price": null,
              "expires_at": null
            }
          ]
        }
      },
      "invoices": []
    }
  ],
  "next_cursor": null
}

Changes

No recorded changes to this operation across all 1 revision of this API.