Skip to content
Docs
APISign inStart free

List invitations

The invitations.list operation: GET /api/v1/invitations in the REST API and the invitations_list tool in the MCP server.

GET/api/v1/invitations

Lists the organization's invitations, newest first, with their status: pending, accepted, revoked or expired (invitations work for 7 days). Filter with status, e.g. pending for the invitations still waiting for an answer. Tokens are never returned. Paginate with limit and starting_after.

Needs members:read (organization owners and admins, or an org management key).

At a glance

  • REST: GET /api/v1/invitations
  • MCP tool: invitations_list
  • Operation ID: invitations.list
  • Scope: Organization
  • Permission: members:read
  • Risk tier: read
  • Dry run: Not supported
  • Idempotency: Not needed (read only)
  • Modes: Test and live
  • Pagination: limit (at most 100) and starting_after
  • Authentication: API key with the members:read scope
  • Since: M1

Request

Query parameters

FieldTypeRequiredDescription
statusone of pending, accepted, revoked, expiredNo
limitinteger (1 to 100)No
starting_afterinvt_… IDNo

Response

200 OK with a JSON object, a page of the list (newest first):

FieldTypeDescription
object"list"
dataarray of object
data[].idinvt_… ID
data[].object"invitation"
data[].orgIdorg_… ID
data[].emailstring
data[].roleone of org_owner, org_admin, billing_admin, finance, tax_manager, support, developer, viewer
data[].scopeobject
data[].statusone of pending, accepted, revoked, expired
data[].expiresAtdate-time
data[].invitedByusr_… ID
data[].acceptedAtdate-time or null
data[].revokedAtdate-time or null
data[].createdAtdate-time
has_moreboolean
next_cursorinvt_… ID or null

Examples

Pending invitations

HTTP
GET /api/v1/invitations?status=pending
Authorization: Bearer or_test_…

Response (200):

JSON
{
  "object": "list",
  "data": [
    {
      "id": "invt_01m4tx5nj8emwbyf7y9vcf47x8",
      "object": "invitation",
      "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
      "email": "finance@acme.example",
      "role": "finance",
      "scope": {
        "type": "entity",
        "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2"
      },
      "status": "pending",
      "expiresAt": "2026-10-20T12:00:00.000Z",
      "invitedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
      "acceptedAt": null,
      "revokedAt": null,
      "createdAt": "2026-10-13T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Everything, two per page

HTTP
GET /api/v1/invitations?limit=2
Authorization: Bearer or_test_…

Response (200):

JSON
{
  "object": "list",
  "data": [
    {
      "id": "invt_01m4tx5nj8emwbyf7y9vcf47x8",
      "object": "invitation",
      "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
      "email": "finance@acme.example",
      "role": "finance",
      "scope": {
        "type": "entity",
        "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2"
      },
      "status": "pending",
      "expiresAt": "2026-10-20T12:00:00.000Z",
      "invitedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
      "acceptedAt": null,
      "revokedAt": null,
      "createdAt": "2026-10-13T12:00:00.000Z"
    },
    {
      "id": "invt_01m4tx5nj8emwbyf7y9vcf47x9",
      "object": "invitation",
      "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
      "email": "dev@acme.example",
      "role": "developer",
      "scope": {
        "type": "brand",
        "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4"
      },
      "status": "accepted",
      "expiresAt": "2026-10-20T12:00:00.000Z",
      "invitedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
      "acceptedAt": "2026-10-14T09:30:00.000Z",
      "revokedAt": null,
      "createdAt": "2026-10-13T12:00:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "invt_01m4tx5nj8emwbyf7y9vcf47x9"
}

Errors

CodeHTTP statusWhenWhat to do
validation_failed400A filter or pagination value is malformed.Fix the fields listed in details.issues and send the request again.
permission_denied403You can't see this organization's members.Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, resource_not_found, dry_run_not_supported, rate_limited, internal_error.