Signup cohorts

curl "https://app.nautilus.co/api/v1/cohorts?start=2026-01-01&end=2026-06-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://app.nautilus.co/api/v1/cohorts?dimension=plan&start=2026-01-01&end=2026-06-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://app.nautilus.co/api/v1/cohorts?dimension=site&start=2026-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "organizationId": "<string>",
  "dateRange": {
    "start": "2023-11-07T05:31:56Z",
    "end": "2023-11-07T05:31:56Z"
  },
  "source": "<string>",
  "available": true,
  "signupDateCoverage": {
    "includedMemberships": 123,
    "membershipsWithoutSignupDate": 123,
    "handling": "<string>"
  },
  "dimensionValues": {
    "limit": 123,
    "included": 123,
    "total": 123,
    "truncated": true
  },
  "cohorts": [
    {
      "cohortMonth": "<string>",
      "dimensionValue": {
        "type": "<string>",
        "planName": "<string>"
      },
      "cohortSize": 123,
      "stillActive": 123,
      "churned": 123,
      "voluntary": 123,
      "involuntary": 123,
      "churnRatePct": 123,
      "churnWithin": {
        "days0To30": 123,
        "days31To90": 123,
        "days91To180": 123,
        "days181To365": 123,
        "days365Plus": 123,
        "unknown": 123
      }
    }
  ]
}

GET

api

cohorts

curl "https://app.nautilus.co/api/v1/cohorts?start=2026-01-01&end=2026-06-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://app.nautilus.co/api/v1/cohorts?dimension=plan&start=2026-01-01&end=2026-06-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://app.nautilus.co/api/v1/cohorts?dimension=site&start=2026-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "organizationId": "<string>",
  "dateRange": {
    "start": "2023-11-07T05:31:56Z",
    "end": "2023-11-07T05:31:56Z"
  },
  "source": "<string>",
  "available": true,
  "signupDateCoverage": {
    "includedMemberships": 123,
    "membershipsWithoutSignupDate": 123,
    "handling": "<string>"
  },
  "dimensionValues": {
    "limit": 123,
    "included": 123,
    "total": 123,
    "truncated": true
  },
  "cohorts": [
    {
      "cohortMonth": "<string>",
      "dimensionValue": {
        "type": "<string>",
        "planName": "<string>"
      },
      "cohortSize": 123,
      "stillActive": 123,
      "churned": 123,
      "voluntary": 123,
      "involuntary": 123,
      "churnRatePct": 123,
      "churnWithin": {
        "days0To30": 123,
        "days31To90": 123,
        "days91To180": 123,
        "days181To365": 123,
        "days365Plus": 123,
        "unknown": 123
      }
    }
  ]
}

Aggregates signup-month cohorts by membership package or billing site.

This endpoint requires a tenant-scoped API key and is available only for eligible organizations.

curl "https://app.nautilus.co/api/v1/cohorts?start=2026-01-01&end=2026-06-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://app.nautilus.co/api/v1/cohorts?dimension=plan&start=2026-01-01&end=2026-06-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://app.nautilus.co/api/v1/cohorts?dimension=site&start=2026-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

The response includes the applied dimension, signup-date coverage, dimension truncation metadata, and cohort rows.

{
  "organizationId": "org_example_123",
  "dateRange": {
    "start": "2026-01-01T00:00:00.000Z",
    "end": "2026-06-30T00:00:00.000Z"
  },
  "source": "membership_signup",
  "available": true,
  "dimension": "plan",
  "signupDateCoverage": {
    "includedMemberships": 1180,
    "membershipsWithoutSignupDate": 24,
    "handling": "excluded_from_cohorts"
  },
  "dimensionValues": {
    "limit": 250,
    "included": 3,
    "total": 3,
    "truncated": false
  },
  "cohorts": [
    {
      "cohortMonth": "2026-01",
      "dimensionValue": {
        "type": "plan",
        "planName": "Unlimited Plus"
      },
      "cohortSize": 240,
      "stillActive": 198,
      "churned": 42,
      "voluntary": 31,
      "involuntary": 11,
      "churnRatePct": 17.5,
      "churnWithin": {
        "days0To30": 8,
        "days31To90": 12,
        "days91To180": 16,
        "days181To365": 6,
        "days365Plus": 0,
        "unknown": 0
      }
    }
  ]
}

Dimensions

dimension=none returns one row per signup month. dimension=plan groups by the membership’s current POS plan name. dimension=site groups by the membership’s current billing site code and resolved site name. For plan and site, Nautilus returns up to 250 dimension values for the requested range. Check dimensionValues.truncated to see whether lower-volume values were omitted.

Caveats

Memberships without signup dates are excluded from cohort rows and counted in signupDateCoverage.membershipsWithoutSignupDate. The plan and site dimensions use current recurring-account values, not signup-time values. Historical cohort composition can shift when a member changes plan or billing site. There is no normalized promotion or source cohort dimension in the current response.

Errors

400 - Invalid dimension or cohort analytics are not available for this organization.
401 - Missing, invalid, or non-tenant-scoped API key.
500 - Internal server error.

Authorizations

Authorization

string

header

required

Clerk tenant API key. The organizationId encoded by the key is the exact and only tenant scope.

Query Parameters

start

string

Inclusive lower bound on cohort month. The value is truncated to its month.

end

string

Inclusive upper bound on cohort month. The value is truncated to its month.

dimension

enum<string>

default:none

Dimension used to group cohort rows.

Available options:

none,

plan,

site

Response

Cohort analytics response

organizationId

string

required

dateRange

Date range · object

required

Show child attributes

source

string

required

Allowed value: "membership_signup"

available

boolean

required

dimension

enum<string>

required

Available options:

none,

plan,

site

Show child attributes

dimensionValues

object

required

Show child attributes

cohorts

object[]

required

Show child attributes

API documentation

Sites

Products

Checkout links

Purchases

Contacts

Marketing

Forms

Vouchers

Links

Automations

Surveys

Cases

Cancellations

Sonny's POS

Message

Email

Analytics

Integration

Response

Dimensions

Caveats

Errors

Authorizations

Query Parameters

Response

​Response

​Dimensions

​Caveats

​Errors

Authorizations

Query Parameters

Response

Response

Dimensions

Caveats

Errors