Skip to main content
POST
/
ccs
/
v1
/
segmentation
/
stateless
Segment user based on provided events and state only
curl --request POST \
  --url 'https://api.permutive.app/ccs/v1/segmentation/stateless?k=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
  "alias": null,
  "aliases": null,
  "events": [
    {
      "name": "Pageview",
      "time": "2022-06-22T19:40:43.179Z",
      "view_id": "a55a9c8b-4a0b-4fe7-99a9-170624850501",
      "session_id": "1d145310-1338-4ff7-96dd-e6128f54cbe5",
      "properties": {
        "my_property": "interesting"
      }
    },
    {
      "name": "Pageview",
      "time": "2022-06-22T19:40:45.152Z",
      "view_id": "a55a9c8b-4a0b-4fe7-99a9-170624850501",
      "session_id": "1d145310-1338-4ff7-96dd-e6128f54cbe5",
      "properties": {
        "my_object": {
          "inner_property": 42
        }
      }
    }
  ],
  "state": {
    "internal_state": {
      "12345": {
        "0c8b70cdb7": [
          "p",
          1
        ]
      }
    },
    "external_state": {
      "67890": {
        "0c8b70cdb7": [
          "p",
          1
        ]
      }
    },
    "cohorts": [
      "12345",
      "67890"
    ]
  }
}
'
{
  "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
  "state": {
    "internal_state": {
      "12345": {
        "0c8b70cdb7": [
          "p",
          1
        ]
      }
    },
    "external_state": {
      "67890": {
        "0c8b70cdb7": [
          "p",
          1
        ]
      }
    },
    "cohorts": [
      "12345",
      "67890"
    ]
  }
}
This endpoint does not persist state. If you need state persistence, use the Segmentation endpoint instead.

​
When to Use Stateless Segmentation

The stateless endpoint is ideal for:
  • Testing and debugging: Verify cohort logic without affecting production state
  • High-performance scenarios: Skip database reads/writes for faster response times
  • Client-managed state: When you want to manage user state in your own systems

​
User State

You can optionally provide pre-existing user state in the request. The response will include the updated state that you should store and pass back in subsequent requests.
The state field format is internal to Permutive and should not be parsed or modified. Treat it as an opaque blob.

​
Example Usage

​
First Request (No State)

curl -X POST "https://api.permutive.app/ccs/v1/segmentation/stateless?k=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
    "events": [
      {
        "name": "Pageview",
        "time": "2024-01-15T10:30:00Z",
        "properties": {
          "category": "technology"
        }
      }
    ]
  }'

​
Subsequent Request (With State)

curl -X POST "https://api.permutive.app/ccs/v1/segmentation/stateless?k=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
    "events": [
      {
        "name": "Pageview",
        "time": "2024-01-15T10:35:00Z",
        "properties": {
          "category": "sports"
        }
      }
    ],
    "state": {
      "internal_state": { ... },
      "external_state": { ... },
      "cohorts": ["12345", "67890"]
    }
  }'

​
Response

The response includes:
  • user_id: The Permutive User ID
  • state: The updated user state (including cohort memberships)
Store the returned state and include it in your next request to maintain continuity.

Authorizations

​
k
string
query
required

Query Parameters

​
synchronous-validation
boolean
default:false

Validate provided event(s) against their schema before proceeding with segmentation.

By default validation is performed asynchronously after segmentation has been performed and the response has been returned. This can make it difficult to debug issues with invalid events.

It is recommended to use this option only during development and debugging, as validation can be expensive and slow.

Body

application/json

A user identifier and a list of events to be used for segmentation, plus optional pre-existing state for the user.

The user identifier must be either a user_id, an alias, or a list of prioritised aliases.

The largest number of events that can currently be included in a single request is 10.

State is in the JSON format returned by this endpoint. It is not intended to be parsed or understood outside the context of this API or a Permutive SDK.

​
user_id
string<uuid>
​
alias
Alias · object
​
aliases
PrioritisedAlias · object[]
​
events
Event · object[]
​
state
UserState · object

Response

The Permutive User ID and the user's state (including the list of cohorts of which they are a member).

​
user_id
string<uuid>
required
​
state
UserState · object
required