Skip to content
aerandil.com
GitHub

Read Federated cohort definition

GET
/v1/object-types/hospitality.federated_cohort_definition/objects/{id}
curl --request GET \
  --url https://api.aerandil.com/v1/object-types/hospitality.federated_cohort_definition/objects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Read an existing instance.

Reusable cohort / comp-set policy. Selection rules, geography granularity, time-window rule, minimum thresholds, max- contributor share, stratification fields, suppression rules, and optional excluded-tenants list. A cohort defines who can be compared, not what is computed (proposal 0021 §4.3).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Object id (UUID v7, server-generated at create time).

Query Parameters

Section titled “Query Parameters”
branch
string format: uuid

Read through an open branch’s copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with as_of (422). The branch must exist under the caller’s tenant.

Responses

Section titled “Responses”

200

Section titled “200”

Object found.

Media typeapplication/json
object
created_at
required
string format: date-time
id
required
string format: uuid
object_type
required
Allowed value: hospitality.federated_cohort_definition
properties
required
object
approved_at
Set by review
string format: date-time
cohort_api_name
required
Stable slug
string
cohort_kind
required
Cohort kind
string
Allowed values: market_segment property_type portfolio_segment service_model risk_tier revenue_band usali_department agent_use_case custom_reviewed
display_name
required
Human-readable name
string
dropout_tolerance_fraction
0022 §11.4 honest-majority threshold for secure-aggregation runs: the fraction of dispatched participants that may drop out (terminal dispatch failure / envelope expiry) before the run is failed and its privacy-budget reservation released. Decimal in (0,1]; absent means the §11.4 default of 0.5.
string format: decimal
excluded_tenants
Rare; conflict / legal exclusions. Not visible to participants unless allowed.
Array<string>
geography_granularity
required
Geography granularity
string
Allowed values: none country region city market custom_reviewed
id
required
Cohort id
string
max_contributor_share
required
Prevents one participant from dominating output (decimal in [0,1])
string format: decimal
minimum_properties
required
Overrides program default if stricter
integer
minimum_subjects
Required for person-affecting outputs
integer
minimum_tenants
required
Overrides program default if stricter
integer
program_api_name
required
Owning program reference
string
selection_rules
required
Typed rules over property / venue / outlet / market metadata (JSON)
status
required
Lifecycle status
string
Allowed values: draft approved deprecated
stratification_fields
required
Allowed output slices, e.g. market class or property type
Array<string>
suppression_rules
required
What to suppress when thresholds fail (JSON)
time_window_rule
required
Rolling or fixed reporting window (JSON)
provenance

Per-property source attribution and pins. An entry under properties means the property’s current value came from that source (on the source’s own clock, source_updated_at); an entry under pins is a human override protecting the property from sourced writes.

object
pins
object
key
additional properties
object
pinned_at
string format: date-time
pinned_by
object
reason
required
string
properties
object
key
additional properties
object
external_id
string
recorded_at
required
string format: date-time
source
required
string
source_updated_at
string format: date-time
stream
string
scope
required
One of: discriminator: level
object
level
required
string
Allowed value: tenant
Allowed values: tenant
tenant_id
required
string format: uuid
updated_at
required
string format: date-time
version
required
integer
>= 1
Example
{
  "object_type": "hospitality.federated_cohort_definition",
  "properties": {
    "cohort_kind": "market_segment",
    "geography_granularity": "none",
    "status": "draft"
  },
  "scope": {
    "level": "tenant"
  }
}

Headers

Section titled “Headers”
ETag
string
/^"\d+"$/

Quoted strong validator (RFC 7232 §2.3) carrying the object’s monotonic version. Informational on the read path — object mutation goes through typed actions on /v1/actions/{action}/apply, not raw CRUD.

404

Section titled “404”

No object with that id (or soft-deleted).