> ## Documentation Index > Fetch the complete documentation index at: https://docs.datadash.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Create a cohort > Defines a cohort from criteria. Membership is computed in the background, so the cohort is not usable until GET reports it ready. ## OpenAPI ````yaml /openapi.json post /api/v1/cohorts openapi: 3.0.3 info: title: DataDash Analytics API version: 1.0.0 servers: [] security: - ApiKeyAuth: [] - BearerAuth: [] paths: /api/v1/cohorts: post: tags: - Cohorts summary: Create a cohort description: >- Defines a cohort from criteria. Membership is computed in the background, so the cohort is not usable until GET reports it ready. operationId: createCohort requestBody: content: application/json: schema: properties: description: type: string groups: description: >- Groups of criteria, combined with match. A wallet joins the cohort when the groups it satisfies satisfy that combination. items: $ref: '#/components/schemas/CohortCriteriaGroup' minItems: 1 type: array match: description: >- How the members combine. Required when there is more than one. enum: - AND - OR type: string title: minLength: 1 type: string required: - title - groups type: object required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CohortAccepted' description: cohort accepted for building '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: >- invalid request (malformed body, unknown field, or failed validation) '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: missing or invalid credentials '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: credentials lack access to this resource '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: no such cohort '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: internal error components: schemas: CohortCriteriaGroup: description: A group of criteria combined with the group's match. properties: criteria: items: $ref: '#/components/schemas/CohortCriteria' minItems: 1 type: array match: description: How the members combine. Required when there is more than one. enum: - AND - OR type: string required: - criteria title: Criteria group type: object CohortAccepted: properties: cohortId: pattern: ^[0-9A-HJ-KM-NP-TV-Z]{13}$ type: string executionId: description: The run building the cohort. Poll GET until status is ready. type: string required: - cohortId type: object Error: properties: code: description: machine-readable error code type: string message: description: human-readable description type: string required: - code - message type: object CohortCriteria: description: >- One condition of cohort membership: a measure over a table, or membership of another cohort. The table field selects which form applies. oneOf: - $ref: '#/components/schemas/ActivityCriterion' - $ref: '#/components/schemas/UserPositionCriterion' - $ref: '#/components/schemas/UserTagProfileCriterion' - $ref: '#/components/schemas/UserProfileCriterion' - $ref: '#/components/schemas/SignalScoreCriterion' - $ref: '#/components/schemas/CohortMembershipCriterion' title: Criterion ActivityCriterion: description: Prediction market activity log with enriched metadata properties: activity: description: Which activity to measure. enum: - Buy - Sell type: string condition: $ref: '#/components/schemas/CohortMeasureCondition' filter: $ref: '#/components/schemas/ActivityCriteriaFilter' measure: $ref: '#/components/schemas/ActivityCriterionMeasure' negative: description: >- Match wallets that do NOT satisfy this criterion. Activity table only. type: boolean table: description: Selects Enriched Activities. enum: - activity type: string timeRange: $ref: '#/components/schemas/CohortTimeRange' required: - table - measure - condition - timeRange - activity title: Enriched Activities type: object UserPositionCriterion: description: >- Lifetime trading rollup per (wallet, position token), bought/sold shares and USD, entry/exit prices, realized and unrealized PnL. One row per wallet-position pair, ungrouped, the raw source behind the Active/All/Closed portfolio views, which regroup these rows by position or event. properties: condition: $ref: '#/components/schemas/CohortMeasureCondition' filter: $ref: '#/components/schemas/UserPositionCriteriaFilter' measure: $ref: '#/components/schemas/UserPositionCriterionMeasure' negative: description: >- Match wallets that do NOT satisfy this criterion. Activity table only. type: boolean table: description: Selects User Position. enum: - userPosition type: string required: - table - measure - condition title: User Position type: object UserTagProfileCriterion: description: Per-user per-tag performance profiles by duration properties: condition: $ref: '#/components/schemas/CohortMeasureCondition' filter: $ref: '#/components/schemas/UserTagProfileCriteriaFilter' measure: $ref: '#/components/schemas/UserTagProfileCriterionMeasure' negative: description: >- Match wallets that do NOT satisfy this criterion. Activity table only. type: boolean table: description: Selects User Tag Profile. enum: - userTagProfile type: string required: - table - measure - condition title: User Tag Profile type: object UserProfileCriterion: description: >- Precomputed per-user performance profile (PnL, win rate, volume, ...) with one row per user for a required duration. properties: condition: $ref: '#/components/schemas/CohortMeasureCondition' filter: $ref: '#/components/schemas/UserProfileCriteriaFilter' measure: $ref: '#/components/schemas/UserProfileCriterionMeasure' negative: description: >- Match wallets that do NOT satisfy this criterion. Activity table only. type: boolean table: description: Selects User Profile. enum: - userProfile type: string required: - table - measure - condition title: User Profile type: object SignalScoreCriterion: description: >- Per-(wallet, position) insider score for currently-held legs in active markets properties: condition: $ref: '#/components/schemas/CohortMeasureCondition' filter: $ref: '#/components/schemas/SignalScoreCriteriaFilter' measure: $ref: '#/components/schemas/SignalScoreCriterionMeasure' negative: description: >- Match wallets that do NOT satisfy this criterion. Activity table only. type: boolean table: description: Selects Signal Score. enum: - signalScore type: string required: - table - measure - condition title: Signal Score type: object CohortMembershipCriterion: description: Match wallets by their membership of another cohort you own. properties: cohortId: pattern: ^[0-9A-HJ-KM-NP-TV-Z]{13}$ type: string negative: description: Match wallets NOT in that cohort. type: boolean required: - cohortId title: Cohort membership type: object CohortMeasureCondition: description: >- The threshold the measure must meet. between takes two values, the others one. properties: operator: enum: - lt - lte - gt - gte - between type: string value: oneOf: - title: Single value type: number - items: type: number minItems: 1 title: List of values type: array required: - operator - value title: Condition type: object ActivityCriteriaFilter: description: Filters to apply, combined with AND. Use a group for OR. items: $ref: '#/components/schemas/ActivityCriteriaFilterNode' minItems: 1 type: array ActivityCriterionMeasure: description: >- Aggregate one field, or count rows. Whether an aggregation is required depends on the table: it is omitted for tables holding a single row per wallet. oneOf: - properties: aggregation: enum: - sum - min - max - median - average - p25 - p75 - p90 - p99 - distinctCount type: string field: enum: - wallet - amount - usdPrice - usdAmount - avgBuyingPrice - realizedPnl - realizedPnlPercentage - positionId - marketId - eventId - tagIds - seriesId type: string required: - field title: Field type: object - description: Count the matching rows. properties: totalCount: enum: - true type: boolean required: - totalCount title: Row count type: object title: Measure CohortTimeRange: description: The window the measure covers. Name exactly one kind of range. maxProperties: 1 minProperties: 1 properties: between: description: A fixed range. properties: from: format: date type: string to: format: date type: string required: - from - to type: object last: description: A trailing window. properties: length: minimum: 1 type: integer unit: enum: - day - week - month - quarter - year type: string required: - unit - length type: object since: description: An open-ended range, from a date or the start of a calendar unit. oneOf: - format: date title: Date type: string - properties: range: enum: - week - month - quarter - year type: string required: - range title: Calendar unit type: object title: Time range type: object UserPositionCriteriaFilter: description: Filters to apply, combined with AND. Use a group for OR. items: $ref: '#/components/schemas/UserPositionCriteriaFilterNode' minItems: 1 type: array UserPositionCriterionMeasure: description: >- Aggregate one field, or count rows. Whether an aggregation is required depends on the table: it is omitted for tables holding a single row per wallet. oneOf: - properties: aggregation: enum: - sum - min - max - median - average - p25 - p75 - p90 - p99 - distinctCount type: string field: enum: - userId - positionId - marketId - eventId - tagIds - seriesId - totalBoughtShares - totalBoughtUsd - totalSoldShares - totalSoldUsd - currentlyHeldShares - avgBuyingPrice - avgSellingPrice - realizedPnl - totalBuyCost - realizedPnlPercentage - realizedAvgBuyingPrice - totalTrades - unrealizedUsd - positionSize type: string required: - field title: Field type: object - description: Count the matching rows. properties: totalCount: enum: - true type: boolean required: - totalCount title: Row count type: object title: Measure UserTagProfileCriteriaFilter: description: Filters to apply, combined with AND. Use a group for OR. items: $ref: '#/components/schemas/UserTagProfileCriteriaFilterNode' minItems: 1 type: array UserTagProfileCriterionMeasure: description: >- Aggregate one field, or count rows. Whether an aggregation is required depends on the table: it is omitted for tables holding a single row per wallet. oneOf: - properties: aggregation: enum: - sum - min - max - median - average - p25 - p75 - p90 - p99 - distinctCount type: string field: enum: - realizedPnl - wins - losses - profit - loss - volume - profitFactor - positions - winRate - realizedBuyCost - roi - holdTime - numTrades - numPredictions - avgTradesPerPrediction - rank type: string required: - field title: Field type: object - description: Count the matching rows. properties: totalCount: enum: - true type: boolean required: - totalCount title: Row count type: object title: Measure UserProfileCriteriaFilter: description: Filters to apply, combined with AND. Use a group for OR. items: $ref: '#/components/schemas/UserProfileCriteriaFilterNode' minItems: 1 type: array UserProfileCriterionMeasure: description: >- Aggregate one field, or count rows. Whether an aggregation is required depends on the table: it is omitted for tables holding a single row per wallet. oneOf: - properties: aggregation: enum: - sum - min - max - median - average - p25 - p75 - p90 - p99 - distinctCount type: string field: enum: - realizedPnl - wins - losses - profit - loss - volume - profitFactor - positions - winRate - realizedBuyCost - roi - holdTime - numTrades - numSplitTrades - numMergeTrades - numRedeemTrades - numConvertTrades - numP2pTrades - numPredictions - avgTradesPerPrediction - rank type: string required: - field title: Field type: object - description: Count the matching rows. properties: totalCount: enum: - true type: boolean required: - totalCount title: Row count type: object title: Measure SignalScoreCriteriaFilter: description: Filters to apply, combined with AND. Use a group for OR. items: $ref: '#/components/schemas/SignalScoreCriteriaFilterNode' minItems: 1 type: array SignalScoreCriterionMeasure: description: >- Aggregate one field, or count rows. Whether an aggregation is required depends on the table: it is omitted for tables holding a single row per wallet. oneOf: - properties: aggregation: enum: - sum - min - max - median - average - p25 - p75 - p90 - p99 - distinctCount type: string field: enum: - userId - positionId - marketId - eventId - tagIds - avgEntryPrice - totalBoughtShares - tradeSize - relSize - daysToResolution - pNow - slipAbs - score type: string required: - field title: Field type: object - description: Count the matching rows. properties: totalCount: enum: - true type: boolean required: - totalCount title: Row count type: object title: Measure ActivityCriteriaFilterNode: description: A single condition, or a group combining conditions with AND/OR. oneOf: - $ref: '#/components/schemas/ActivityCriteriaCondition' - $ref: '#/components/schemas/ActivityCriteriaFilterGroup' title: Filter UserPositionCriteriaFilterNode: description: A single condition, or a group combining conditions with AND/OR. oneOf: - $ref: '#/components/schemas/UserPositionCriteriaCondition' - $ref: '#/components/schemas/UserPositionCriteriaFilterGroup' title: Filter UserTagProfileCriteriaFilterNode: description: A single condition, or a group combining conditions with AND/OR. oneOf: - $ref: '#/components/schemas/UserTagProfileCriteriaCondition' - $ref: '#/components/schemas/UserTagProfileCriteriaFilterGroup' title: Filter UserProfileCriteriaFilterNode: description: A single condition, or a group combining conditions with AND/OR. oneOf: - $ref: '#/components/schemas/UserProfileCriteriaCondition' - $ref: '#/components/schemas/UserProfileCriteriaFilterGroup' title: Filter SignalScoreCriteriaFilterNode: description: A single condition, or a group combining conditions with AND/OR. oneOf: - $ref: '#/components/schemas/SignalScoreCriteriaCondition' - $ref: '#/components/schemas/SignalScoreCriteriaFilterGroup' title: Filter ActivityCriteriaCondition: description: >- A single field condition. in/notIn take an array of values; matches/notMatches take one search term. oneOf: - $ref: '#/components/schemas/ActivityCriteriaNumericCondition' - $ref: '#/components/schemas/ActivityCriteriaBigNumberCondition' - $ref: '#/components/schemas/ActivityCriteriaIdCondition' - $ref: '#/components/schemas/ActivityCriteriaAddressCondition' - $ref: '#/components/schemas/ActivityCriteriaTimeCondition' title: Condition ActivityCriteriaFilterGroup: description: A group of conditions, combined with the group's operator. properties: filters: items: $ref: '#/components/schemas/ActivityCriteriaCondition' minItems: 1 type: array operator: enum: - AND - OR type: string required: - operator - filters title: Group type: object UserPositionCriteriaCondition: description: >- A single field condition. in/notIn take an array of values; matches/notMatches take one search term. oneOf: - $ref: '#/components/schemas/UserPositionCriteriaNumericCondition' - $ref: '#/components/schemas/UserPositionCriteriaIdCondition' - $ref: '#/components/schemas/UserPositionCriteriaAddressCondition' - $ref: '#/components/schemas/UserPositionCriteriaTimeCondition' title: Condition UserPositionCriteriaFilterGroup: description: A group of conditions, combined with the group's operator. properties: filters: items: $ref: '#/components/schemas/UserPositionCriteriaCondition' minItems: 1 type: array operator: enum: - AND - OR type: string required: - operator - filters title: Group type: object UserTagProfileCriteriaCondition: description: >- A single field condition. in/notIn take an array of values; matches/notMatches take one search term. oneOf: - $ref: '#/components/schemas/UserTagProfileCriteriaNumericCondition' - $ref: '#/components/schemas/UserTagProfileCriteriaIdCondition' title: Condition UserTagProfileCriteriaFilterGroup: description: A group of conditions, combined with the group's operator. properties: filters: items: $ref: '#/components/schemas/UserTagProfileCriteriaCondition' minItems: 1 type: array operator: enum: - AND - OR type: string required: - operator - filters title: Group type: object UserProfileCriteriaCondition: description: >- A single field condition. in/notIn take an array of values; matches/notMatches take one search term. oneOf: - $ref: '#/components/schemas/UserProfileCriteriaNumericCondition' - $ref: '#/components/schemas/UserProfileCriteriaAddressCondition' title: Condition UserProfileCriteriaFilterGroup: description: A group of conditions, combined with the group's operator. properties: filters: items: $ref: '#/components/schemas/UserProfileCriteriaCondition' minItems: 1 type: array operator: enum: - AND - OR type: string required: - operator - filters title: Group type: object SignalScoreCriteriaCondition: description: >- A single field condition. in/notIn take an array of values; matches/notMatches take one search term. oneOf: - $ref: '#/components/schemas/SignalScoreCriteriaNumericCondition' - $ref: '#/components/schemas/SignalScoreCriteriaIdCondition' - $ref: '#/components/schemas/SignalScoreCriteriaAddressCondition' title: Condition SignalScoreCriteriaFilterGroup: description: A group of conditions, combined with the group's operator. properties: filters: items: $ref: '#/components/schemas/SignalScoreCriteriaCondition' minItems: 1 type: array operator: enum: - AND - OR type: string required: - operator - filters title: Group type: object ActivityCriteriaNumericCondition: properties: field: enum: - amount - usdPrice - usdAmount - avgBuyingPrice - realizedPnl - realizedPnlPercentage - userRank - timestampNum type: string operator: enum: - eq - neq - lt - lte - gt - gte type: string value: oneOf: - format: double title: Single value type: number - items: format: double type: number minItems: 1 title: List of values type: array required: - field - operator - value title: Numeric type: object ActivityCriteriaBigNumberCondition: properties: field: enum: - seqId type: string operator: enum: - eq - neq - lt - lte - gt - gte type: string value: oneOf: - format: big-integer title: Single value type: string - items: format: big-integer type: string minItems: 1 title: List of values type: array required: - field - operator - value title: Large number type: object ActivityCriteriaIdCondition: properties: field: enum: - positionId - marketId - eventId - tagIds - seriesId type: string operator: enum: - in - notIn type: string value: oneOf: - format: int32 title: Single value type: integer - items: format: int32 type: integer minItems: 1 title: List of values type: array required: - field - operator - value title: ID type: object ActivityCriteriaAddressCondition: description: inCohort/notInCohort take cohort ids instead of addresses. properties: field: enum: - wallet type: string operator: enum: - in - notIn - inCohort - notInCohort type: string value: oneOf: - title: Single value type: string - items: type: string minItems: 1 title: List of values type: array required: - field - operator - value title: Wallet address type: object ActivityCriteriaTimeCondition: description: >- last takes {unit, length}; between takes {from, to}; since takes a date or {range}. properties: field: enum: - timestamp type: string operator: enum: - last - between - since type: string value: oneOf: - description: 'last: a trailing window' properties: length: minimum: 1 type: integer unit: enum: - day - week - month - quarter - year type: string required: - unit - length title: Last type: object - description: 'between: a fixed range' properties: from: format: date type: string to: format: date type: string required: - from - to title: Between type: object - description: 'since: an open-ended range from a calendar unit' properties: range: enum: - week - month - quarter - year type: string required: - range title: Since calendar unit type: object - description: 'since: an open-ended range from a date' format: date title: Since date type: string required: - field - operator - value title: Time range type: object UserPositionCriteriaNumericCondition: properties: field: enum: - totalBoughtShares - totalBoughtUsd - totalSoldShares - totalSoldUsd - currentlyHeldShares - avgBuyingPrice - avgSellingPrice - realizedPnl - totalBuyCost - realizedAvgBuyingPrice - totalTrades - unrealizedUsd - positionSize type: string operator: enum: - eq - neq - lt - lte - gt - gte type: string value: oneOf: - format: double title: Single value type: number - items: format: double type: number minItems: 1 title: List of values type: array required: - field - operator - value title: Numeric type: object UserPositionCriteriaIdCondition: properties: field: enum: - positionId - marketId - eventId - tagIds - seriesId type: string operator: enum: - in - notIn type: string value: oneOf: - format: int32 title: Single value type: integer - items: format: int32 type: integer minItems: 1 title: List of values type: array required: - field - operator - value title: ID type: object UserPositionCriteriaAddressCondition: description: inCohort/notInCohort take cohort ids instead of addresses. properties: field: enum: - userId type: string operator: enum: - in - notIn - inCohort - notInCohort type: string value: oneOf: - title: Single value type: string - items: type: string minItems: 1 title: List of values type: array required: - field - operator - value title: Wallet address type: object UserPositionCriteriaTimeCondition: description: >- last takes {unit, length}; between takes {from, to}; since takes a date or {range}. properties: field: enum: - firstTradeTimestamp - latestTradeTimestamp type: string operator: enum: - last - between - since type: string value: oneOf: - description: 'last: a trailing window' properties: length: minimum: 1 type: integer unit: enum: - day - week - month - quarter - year type: string required: - unit - length title: Last type: object - description: 'between: a fixed range' properties: from: format: date type: string to: format: date type: string required: - from - to title: Between type: object - description: 'since: an open-ended range from a calendar unit' properties: range: enum: - week - month - quarter - year type: string required: - range title: Since calendar unit type: object - description: 'since: an open-ended range from a date' format: date title: Since date type: string required: - field - operator - value title: Time range type: object UserTagProfileCriteriaNumericCondition: properties: field: enum: - realizedPnl - wins - losses - profit - loss - volume - profitFactor - positions - winRate - realizedBuyCost - roi - holdTime - numTrades - numPredictions - avgTradesPerPrediction - rank type: string operator: enum: - eq - neq - lt - lte - gt - gte type: string value: oneOf: - format: double title: Single value type: number - items: format: double type: number minItems: 1 title: List of values type: array required: - field - operator - value title: Numeric type: object UserTagProfileCriteriaIdCondition: properties: field: enum: - tagId type: string operator: enum: - in - notIn type: string value: oneOf: - format: int32 title: Single value type: integer - items: format: int32 type: integer minItems: 1 title: List of values type: array required: - field - operator - value title: ID type: object UserProfileCriteriaNumericCondition: properties: field: enum: - realizedPnl - wins - losses - profit - loss - volume - profitFactor - positions - winRate - realizedBuyCost - roi - holdTime - numTrades - numSplitTrades - numMergeTrades - numRedeemTrades - numConvertTrades - numP2pTrades - numPredictions - avgTradesPerPrediction - rank type: string operator: enum: - eq - neq - lt - lte - gt - gte type: string value: oneOf: - format: double title: Single value type: number - items: format: double type: number minItems: 1 title: List of values type: array required: - field - operator - value title: Numeric type: object UserProfileCriteriaAddressCondition: description: inCohort/notInCohort take cohort ids instead of addresses. properties: field: enum: - userId type: string operator: enum: - in - notIn - inCohort - notInCohort type: string value: oneOf: - title: Single value type: string - items: type: string minItems: 1 title: List of values type: array required: - field - operator - value title: Wallet address type: object SignalScoreCriteriaNumericCondition: properties: field: enum: - avgEntryPrice - totalBoughtShares - tradeSize - relSize - daysToResolution - pNow - slipAbs - score - userRank type: string operator: enum: - eq - neq - lt - lte - gt - gte type: string value: oneOf: - format: double title: Single value type: number - items: format: double type: number minItems: 1 title: List of values type: array required: - field - operator - value title: Numeric type: object SignalScoreCriteriaIdCondition: properties: field: enum: - positionId - marketId - eventId - tagIds type: string operator: enum: - in - notIn type: string value: oneOf: - format: int32 title: Single value type: integer - items: format: int32 type: integer minItems: 1 title: List of values type: array required: - field - operator - value title: ID type: object SignalScoreCriteriaAddressCondition: description: inCohort/notInCohort take cohort ids instead of addresses. properties: field: enum: - userId type: string operator: enum: - in - notIn - inCohort - notInCohort type: string value: oneOf: - title: Single value type: string - items: type: string minItems: 1 title: List of values type: array required: - field - operator - value title: Wallet address type: object securitySchemes: ApiKeyAuth: description: API key issued for programmatic access. in: header name: X-Api-Key type: apiKey BearerAuth: bearerFormat: JWT description: User access token. scheme: bearer type: http ````