curl --request PATCH \
  --url 'https://api.permutive.app/cohorts-api/v2/cohorts/{cohortId}?k=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "New Segment Name",
  "description": "New Segment Description",
  "query": {
    "event": "Pageview",
    "frequency": {
      "greater_than_or_equal_to": 2
    },
    "where": {
      "property": "properties.client.url",
      "condition": {
        "contains": "football"
      }
    },
    "during": {
      "the_last": {
        "value": 30,
        "unit": "days"
      }
    }
  },
  "tags": [
    "tag_d",
    "tag_e"
  ]
}
'

{
  "id": "38470a62-9837-4c86-bbf3-45dd6d52dd83",
  "code": 12345,
  "name": "Example Segment A",
  "description": "This segment is an example for documentation purposes",
  "query": {
    "event": "Pageview",
    "frequency": {
      "greater_than_or_equal_to": 2
    },
    "where": {
      "property": "properties.client.url",
      "condition": {
        "contains": "football"
      }
    },
    "during": {
      "the_last": {
        "value": 30,
        "unit": "days"
      }
    }
  },
  "tags": [
    "tag_a",
    "tag_b"
  ],
  "state": "Enabled",
  "segment_type": "real_time",
  "created_at": "2022-09-22T15:44:29.518935935Z",
  "last_updated_at": "2022-09-22T15:44:29.518937018Z"
}

Cohorts API

Update a cohort

This endpoint allows updating an existing cohort. Depending on the access level of the provided API key, it can update cohorts owned by the requesting workspace, or also by child workspaces below the requesting workspace in the organization hierarchy. Lookalike-based cohorts cannot be updated via the Cohort API.

Any top level fields for which no value is provided in the request body will remain unchanged. Optional fields (currently only description) can be deleted by explicitly specifying null as the value.

PATCH

cohorts

{cohortId}

curl --request PATCH \
  --url 'https://api.permutive.app/cohorts-api/v2/cohorts/{cohortId}?k=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "New Segment Name",
  "description": "New Segment Description",
  "query": {
    "event": "Pageview",
    "frequency": {
      "greater_than_or_equal_to": 2
    },
    "where": {
      "property": "properties.client.url",
      "condition": {
        "contains": "football"
      }
    },
    "during": {
      "the_last": {
        "value": 30,
        "unit": "days"
      }
    }
  },
  "tags": [
    "tag_d",
    "tag_e"
  ]
}
'

{
  "id": "38470a62-9837-4c86-bbf3-45dd6d52dd83",
  "code": 12345,
  "name": "Example Segment A",
  "description": "This segment is an example for documentation purposes",
  "query": {
    "event": "Pageview",
    "frequency": {
      "greater_than_or_equal_to": 2
    },
    "where": {
      "property": "properties.client.url",
      "condition": {
        "contains": "football"
      }
    },
    "during": {
      "the_last": {
        "value": 30,
        "unit": "days"
      }
    }
  },
  "tags": [
    "tag_a",
    "tag_b"
  ],
  "state": "Enabled",
  "segment_type": "real_time",
  "created_at": "2022-09-22T15:44:29.518935935Z",
  "last_updated_at": "2022-09-22T15:44:29.518937018Z"
}

Authorizations

string

query

required

Path Parameters

cohortId

string

required

Cohort UUID

Body

application/json

name

string

description

string | null

query

any

Response

Cohort in full (including query)

string

required

code

integer

required

name

string

required

query

any

required

state

enum<string>

required

Available options:

Enabled,

Disabled

segmentType

object

required

Option 1
Option 2

createdAt

string<date-time>

required

lastUpdatedAt

string<date-time>

required

description

string