Create cohort

posthttps://api.faraday.ai/v1/cohorts

Add a new cohort (defined as people who have made qualifying emissions of certain events)

Authentication

Bearer Authentication

Provide your API key in the Authorization header. You can find your API key in the Settings page of the dashboard.

Authorization: Bearer YOUR_TOKEN

Body

The definition of the new cohort

exploreboolean

Whether to show the Cohort in Explore, the map view on https://app.faraday.ai.

This will slow down Cohort builds.

Example: false

max_countnumber

Max count for this cohort's config

Example: 100

max_valuenumber

Max value for this cohort's config

Example: 100

min_countnumber

Min count for this cohort's config

Example: 10

min_valuenumber

Min value for this cohort's config

Example: 100

namestringrequired

Human-readable label for this cohort.

Example: "Customers"

Match pattern: ^(?!\s*$).+

place_conditionsarray[object]

List of places to use to spatially filter Cohort membership.

Items of array[object]

distanceinteger

A distance in meters which will be used to expand the Place's geometry. By default, the distance is set to 0 which means using the geometry itself, explicitly set your own value to override this. If t...

Example: 0

invertboolean

By default, Place conditions will select people who intersect the place's geometry. If invert is set to true, then
instead, select people who do not intersect the Place's geometry.

Example: false

place_idstring<uuid>required

The ID of a Place which should be used to filter this Cohort's membership spatially.

recencyobject

(Parameters used to POST a new value of the Recency type.)

Basing cohort on recency of event

Properties of object

max_daysinteger

Event must have occurred no more than N days ago

min_daysinteger

Event must have occurred at least N days ago

occurrencestringrequired

What event to pay attention to

Allowed values: first, last

stream_conditionsarray[object]

List of stream properties to filter cohort membership on. The stream properties must be for the same stream set as the cohort stream_name.

Nulls are excluded unless explicitly requested with _null: true.

Items of array[object]

_eqstring

Equal to

_gtnumber

Greater than

_gtenumber

Greater than or equal to

_inarray[string]

Value is one of

_ltnumber

Less than

_ltenumber

Less than or equal to

_matchesstring

Value contains a match to the regex (re2) expression provided. For an exact regex match, use the ^ and $ characters as specified by the (re2 documentation)[https://github.com/google/re2/wiki/Syntax].

_ninarray[string]

Value is not one of

_nnullboolean

Value is not null

_nullboolean

Value is null (nulls are otherwise excluded)

optionalboolean

Optional stream conditions are unioned together, when combined they define cohorts that meet either stream condition. At least one optional condition must be satisfied.

propertystringrequired

Stream property name.

stream_namestring

The name field of the stream from which to build this cohort.

Example: "orders"

traitsarray[object]

List of traits to filter cohort membership

Items of array[object]

_eqstring

Equal to

_gtnumber

Greater than

_gtenumber

Greater than or equal to

_inarray[string]

Value is one of

_ltnumber

Less than

_ltenumber

Less than or equal to

_matchesstring

Value contains a match to the regex (re2) expression provided. For an exact regex match, use the ^ and $ characters as specified by the (re2 documentation)[https://github.com/google/re2/wiki/Syntax].

_ninarray[string]

Value is not one of

_nnullboolean

Value is not null

_nullboolean

Value is null (nulls are otherwise excluded)

namestringrequired

The name of the trait.

optionalboolean

Optional trait conditions are unioned together, when combined they define cohorts that meet either trait condition - i.e. state = WA OR metro = Portland. At least one optional condition must be satisfied.

Responses

201The new cohort

archived_atstring<date-time>

If not null, this resource will no longer receive updates, but will still be visable.

classicboolean

A Managed Cohort.

created_atstring<date-time>required

When this resource was created.

exploreboolean

Whether to show the Cohort in Explore, the map view on https://app.faraday.ai.

This will slow down Cohort builds.

Example: false

idstring<uuid>required

A unique ID for this resource.

Example: "5bf9aa70-7bf1-4ef1-a131-8c84441be231"

last_read_input_atstring<date-time>

The last time this resource's input was read.

last_updated_config_atstring<date-time>

The last time this resource's configuration was updated. If this is more recent than last_updated_output_at, the resource will be rebuilt.

last_updated_output_atstring<date-time>

The last time this resource successfully built.

max_countnumber

Max count for this cohort's config

Example: 100

max_valuenumber

Max value for this cohort's config

Example: 100

min_countnumber

Min count for this cohort's config

Example: 10

min_valuenumber

Min value for this cohort's config

Example: 100

namestringrequired

Human-readable label for this cohort.

Example: "Customers"

Match pattern: ^(?!\s*$).+

place_conditionsarray[object]

List of places to use to spatially filter Cohort membership.

Items of array[object]

distanceinteger

Example: 0

invertboolean

By default, Place conditions will select people who intersect the place's geometry. If invert is set to true, then
instead, select people who do not intersect the Place's geometry.

Example: false

place_idstring<uuid>required

The ID of a Place which should be used to filter this Cohort's membership spatially.

population_countinteger

Count of unique individuals.

recencyobject

Basing cohort on recency of event

Properties of object

max_daysinteger

Event must have occurred no more than N days ago

min_daysinteger

Event must have occurred at least N days ago

occurrencestringrequired

What event to pay attention to

Allowed values: first, last

residence_countinteger

Count of unique residences.

resource_typestringrequired

The type of this resource.

Example: "cohorts"

statusstringrequired

The current state of this resource and any updates.

Example: "pending"

Allowed values: new, starting, running, ready, error

status_changed_atstring<date-time>

When the status of this resource was last updated.

status_errorstring

If this resource has status == "error", this will contain an error message.

stream_conditionsarray[object]

List of stream properties to filter cohort membership on. The stream properties must be for the same stream set as the cohort stream_name.

Nulls are excluded unless explicitly requested with _null: true.

Items of array[object]

_eqstring

Equal to

_gtnumber

Greater than

_gtenumber

Greater than or equal to

_inarray[string]

Value is one of

_ltnumber

Less than

_ltenumber

Less than or equal to

_matchesstring

Value contains a match to the regex (re2) expression provided. For an exact regex match, use the ^ and $ characters as specified by the (re2 documentation)[https://github.com/google/re2/wiki/Syntax].

_ninarray[string]

Value is not one of

_nnullboolean

Value is not null

_nullboolean

Value is null (nulls are otherwise excluded)

optionalboolean

Optional stream conditions are unioned together, when combined they define cohorts that meet either stream condition. At least one optional condition must be satisfied.

propertystringrequired

Stream property name.

stream_namestring

The name field of the stream from which to build this cohort.

Example: "orders"

traitsarray[object]

List of traits to filter cohort membership

Items of array[object]

_eqstring

Equal to

_gtnumber

Greater than

_gtenumber

Greater than or equal to

_inarray[string]

Value is one of

_ltnumber

Less than

_ltenumber

Less than or equal to

_matchesstring

Value contains a match to the regex (re2) expression provided. For an exact regex match, use the ^ and $ characters as specified by the (re2 documentation)[https://github.com/google/re2/wiki/Syntax].

_ninarray[string]

Value is not one of

_nnullboolean

Value is not null

_nullboolean

Value is null (nulls are otherwise excluded)

namestringrequired

The name of the trait.

optionalboolean

updated_atstring<date-time>required

When this resource was last updated.

400The request was invalid.

errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

BAD_REQUEST: The request could not be validated.
FORBIDDEN: You do not have permission to access the specified resour...

Example: "ERROR_TYPE"

Allowed values:

BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT

idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"

notestringrequired

A human-readable description of the error.

Example: "An error occurred"

validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]

contextobjectrequired

More information about the error.

Properties of object

errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

401No API key was supplied.

errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

BAD_REQUEST: The request could not be validated.
FORBIDDEN: You do not have permission to access the specified resour...

Example: "ERROR_TYPE"

Allowed values:

BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT

idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"

notestringrequired

A human-readable description of the error.

Example: "An error occurred"

validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]

contextobjectrequired

More information about the error.

Properties of object

errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

403Access to this resource was forbidden.

errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

BAD_REQUEST: The request could not be validated.
FORBIDDEN: You do not have permission to access the specified resour...

Example: "ERROR_TYPE"

Allowed values:

BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT

idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"

notestringrequired

A human-readable description of the error.

Example: "An error occurred"

validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]

contextobjectrequired

More information about the error.

Properties of object

errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

404The requested resource ID was not found.

errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

BAD_REQUEST: The request could not be validated.
FORBIDDEN: You do not have permission to access the specified resour...

Example: "ERROR_TYPE"

Allowed values:

BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT

idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"

notestringrequired

A human-readable description of the error.

Example: "An error occurred"

validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]

contextobjectrequired

More information about the error.

Properties of object

errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

500An internal server error occurred.

errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

BAD_REQUEST: The request could not be validated.
FORBIDDEN: You do not have permission to access the specified resour...

Example: "ERROR_TYPE"

Allowed values:

BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT

idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"

notestringrequired

A human-readable description of the error.

Example: "An error occurred"

validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]

contextobjectrequired

More information about the error.

Properties of object

errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

Tags

cohorts

Test request

API key

Prefer using test/development API keys here.

Request body (JSON)

{
  "explore": false,
  "max_count": 100,
  "max_value": 100,
  "min_count": 10,
  "min_value": 100,
  "name": "Customers",
  "place_conditions": [
    {
      "distance": 0,
      "invert": false,
      "place_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "recency": {
    "max_days": 0,
    "min_days": 0,
    "occurrence": "first"
  },
  "stream_conditions": [
    {
      "_eq": "string",
      "_gt": 0,
      "_gte": 0,
      "_in": [
        "string"
      ],
      "_lt": 0,
      "_lte": 0,
      "_matches": "string",
      "_nin": [
        "string"
      ],
      "_nnull": true,
      "_null": true,
      "optional": true,
      "property": "string"
    }
  ],
  "stream_name": "orders",
  "traits": [
    {
      "_eq": "string",
      "_gt": 0,
      "_gte": 0,
      "_in": [
        "string"
      ],
      "_lt": 0,
      "_lte": 0,
      "_matches": "string",
      "_nin": [
        "string"
      ],
      "_nnull": true,
      "_null": true,
      "name": "string",
      "optional": true
    }
  ]
}

Request snippet

curl -X POST 'https://api.faraday.ai/v1/cohorts' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
      "explore": false,
      "max_count": 100,
      "max_value": 100,
      "min_count": 10,
      "min_value": 100,
      "name": "Customers",
      "place_conditions": [
        {
          "distance": 0,
          "invert": false,
          "place_id": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "recency": {
        "max_days": 0,
        "min_days": 0,
        "occurrence": "first"
      },
      "stream_conditions": [
        {
          "_eq": "string",
          "_gt": 0,
          "_gte": 0,
          "_in": [
            "string"
          ],
          "_lt": 0,
          "_lte": 0,
          "_matches": "string",
          "_nin": [
            "string"
          ],
          "_nnull": true,
          "_null": true,
          "optional": true,
          "property": "string"
        }
      ],
      "stream_name": "orders",
      "traits": [
        {
          "_eq": "string",
          "_gt": 0,
          "_gte": 0,
          "_in": [
            "string"
          ],
          "_lt": 0,
          "_lte": 0,
          "_matches": "string",
          "_nin": [
            "string"
          ],
          "_nnull": true,
          "_null": true,
          "name": "string",
          "optional": true
        }
      ]
    }'

Example response

application/json

{
  "archived_at": "2024-01-01T12:00:00Z",
  "classic": true,
  "created_at": "2024-01-01T12:00:00Z",
  "explore": false,
  "id": "5bf9aa70-7bf1-4ef1-a131-8c84441be231",
  "last_read_input_at": "2024-01-01T12:00:00Z",
  "last_updated_config_at": "2024-01-01T12:00:00Z",
  "last_updated_output_at": "2024-01-01T12:00:00Z",
  "max_count": 100,
  "max_value": 100,
  "min_count": 10,
  "min_value": 100,
  "name": "Customers",
  "place_conditions": [
    {
      "distance": 0,
      "invert": false,
      "place_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "population_count": 0,
  "recency": {
    "max_days": 0,
    "min_days": 0,
    "occurrence": "first"
  },
  "residence_count": 0,
  "resource_type": "cohorts",
  "status": "pending",
  "status_changed_at": "2024-01-01T12:00:00Z",
  "status_error": "string",
  "stream_conditions": [
    {
      "_eq": "string",
      "_gt": 0,
      "_gte": 0,
      "_in": [
        "string"
      ],
      "_lt": 0,
      "_lte": 0,
      "_matches": "string",
      "_nin": [
        "string"
      ],
      "_nnull": true,
      "_null": true,
      "optional": true,
      "property": "string"
    }
  ],
  "stream_name": "orders",
  "traits": [
    {
      "_eq": "string",
      "_gt": 0,
      "_gte": 0,
      "_in": [
        "string"
      ],
      "_lt": 0,
      "_lte": 0,
      "_matches": "string",
      "_nin": [
        "string"
      ],
      "_nnull": true,
      "_null": true,
      "name": "string",
      "optional": true
    }
  ],
  "updated_at": "2024-01-01T12:00:00Z"
}