Edit a cohort
https://api.faraday.ai/v1/cohorts/{cohort_id}Edit configuration of a cohort
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_TOKENpath parameters
The UUID of a cohort
Body
Fields to update on the existing cohort. To delete an optional field, set it to null.
attributesone of 2 typesList of attribute conditions to filter cohort membership. Faraday-provided (fig/) conditions go here, not in traits.
Attribute conditions and trait conditions merge into one list. Required condit...
exploreone of 2 typesDeprecated. Always false. Faraday ignores this field in requests.
location_conditionsone of 2 typesList of atlas locations to use to spatially filter Cohort membership.
A cohort may not set both location_conditions and place_conditions.
max_countone of 2 typesMax count for this cohort's config
max_valueone of 2 typesMax value for this cohort's config
min_countone of 2 typesMin count for this cohort's config
min_valueone of 2 typesMin value for this cohort's config
namestringHuman-readable label for this cohort.
"Customers"^(?!\s*$).+64place_conditionsone of 2 typesList of places to use to spatially filter Cohort membership.
Superseded by location_conditions, which filters on the locations of an atlas. A cohort may not set both.
recencyone of 2 typesstream_conditionsone of 2 typesList 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.
stream_nameone of 2 typesThe name field of the stream from which to build this cohort.
traitsone of 2 typesList of traits to filter cohort membership
Responses
200The updated cohort
archived_atstring<date-time>If not null, this resource will no longer receive updates, but will still be visable.
attributesarray[object]List of attribute conditions to filter cohort membership. Faraday-provided (fig/) conditions go here, not in traits.
Attribute conditions and trait conditions merge into one list. Required condit...
When this resource was created. It says nothing about builds; to check status, see Status and timestamps.
Deprecated. Always false. Faraday ignores this field in requests.
falsefalseA unique ID for this resource.
"5bf9aa70-7bf1-4ef1-a131-8c84441be231"last_read_input_atstring<date-time>When the latest finished build started reading this resource's configuration and inputs; omitted until the first build finishes. Once this is at or after last_updated_config_at, a build with the cur...
last_updated_config_atstring<date-time>When Faraday registered the latest change to this resource's configuration, or the latest force_update. A create, update or force_update response carries the value then on record (an update that c...
last_updated_output_atstring<date-time>When a build last changed this resource's output. A build that finishes with nothing new to write does not move it.
location_conditionsarray[object]List of atlas locations to use to spatially filter Cohort membership.
A cohort may not set both location_conditions and place_conditions.
metricsobjectHuman-readable label for this cohort.
"Customers"^(?!\s*$).+64List of places to use to spatially filter Cohort membership.
Superseded by location_conditions, which filters on the locations of an atlas. A cohort may not set both.
Count of unique individuals.
Count of unique residences.
The state of this resource's latest build. Until last_read_input_at is at or after last_updated_config_at, no build with the current configuration has finished (starting or running means one i...
"ready"new, starting, running, ready, errorstatus_changed_atstring<date-time>When the status of this resource was last updated.
status_errorstringIf this resource has status == "error", this will contain an error message.
status_needs_fix_fromstringWhat Faraday is waiting for before it builds a resource with status == "error" again. user: a configuration change to this resource or a force_update. support: Faraday support, and `force_upda...
user, supportstream_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.
stream_namestringThe name field of the stream from which to build this cohort.
"orders"64traitsarray[object]List of traits to filter cohort membership
When this resource was last changed, by an edit or by Faraday while building it. Don't use it to check status; use last_updated_config_at and last_read_input_at as Status and timestamps explains.
400The request was invalid.
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...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDEDA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
401No API key was supplied.
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...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDEDA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
403Access to this resource was forbidden.
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...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDEDA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
404The requested resource ID was not found.
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...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDEDA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
409The request was formatted correctly, but conflicted with an existing resource.
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...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDEDA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
500An internal server error occurred.
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...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDEDA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
Tags
Test request
Request snippet
curl -X PATCH 'https://api.faraday.ai/v1/cohorts/{cohort_id}' \
-H 'Content-Type: application/merge-patch+json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"attributes": [
{
"_eq": "string",
"_gt": 0,
"_gte": 0,
"_in": [
"string"
],
"_lt": 0,
"_lte": 0,
"_matches": "string",
"_nin": [
"string"
],
"_nnull": true,
"_null": true,
"name": "string",
"optional": true
}
],
"explore": false,
"location_conditions": [
{
"distance": 0,
"invert": false,
"locations": {
"atlas_ids": [
"4c6c0f1e-0a58-4f1a-9c8a-52a1a1a3f5b7"
],
"location_reference_keys": [
"store-042"
],
"property_conditions": [
{
"_eq": "string",
"_gt": 0,
"_gte": 0,
"_in": [
"string"
],
"_lt": 0,
"_lte": 0,
"_matches": "string",
"_neq": "string",
"_nin": [
"string"
],
"_nnull": true,
"_null": true,
"optional": true,
"property": "string"
}
]
}
}
],
"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,
"_on_or_after": "2024-01-01",
"_on_or_before": "2024-01-01",
"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
{
"archived_at": "2024-01-01T12:00:00Z",
"attributes": [
{
"_eq": "string",
"_gt": 0,
"_gte": 0,
"_in": [
"string"
],
"_lt": 0,
"_lte": 0,
"_matches": "string",
"_nin": [
"string"
],
"_nnull": true,
"_null": true,
"name": "string",
"optional": true
}
],
"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",
"location_conditions": [
{
"distance": 0,
"invert": false,
"locations": {
"atlas_ids": [
"4c6c0f1e-0a58-4f1a-9c8a-52a1a1a3f5b7"
],
"location_reference_keys": [
"store-042"
],
"property_conditions": [
{
"_eq": "string",
"_gt": 0,
"_gte": 0,
"_in": [
"string"
],
"_lt": 0,
"_lte": 0,
"_matches": "string",
"_neq": "string",
"_nin": [
"string"
],
"_nnull": true,
"_null": true,
"optional": true,
"property": "string"
}
]
}
}
],
"max_count": 100,
"max_value": 100,
"metrics": {
"enrichable_person_count": 0,
"enrichable_residence_count": 0,
"total_person_count": 0,
"total_residence_count": 0
},
"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": "ready",
"status_changed_at": "2024-01-01T12:00:00Z",
"status_error": "string",
"status_needs_fix_from": "user",
"stream_conditions": [
{
"_eq": "string",
"_gt": 0,
"_gte": 0,
"_in": [
"string"
],
"_lt": 0,
"_lte": 0,
"_matches": "string",
"_nin": [
"string"
],
"_nnull": true,
"_null": true,
"_on_or_after": "2024-01-01",
"_on_or_before": "2024-01-01",
"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"
}