---
title: "Creates a new ranking flow."
method: POST
path: "/flow/ranking"
tags: ["RankingFlow"]
---

# Creates a new ranking flow.

`POST /flow/ranking`

## Request body

- CreateFlowEndpointInput
  - `name` string, required — The name of the ranking flow.
  - `criteria` string, required — The ranking criteria used to compare items.
  - `audienceId` string, nullable — Optional audience ID. When provided, the flow will only be served to users in this audience.
  - `validationSetId` string, nullable — Optional ID of the validation set to use.
  - `startingElo` integer, nullable — Initial Elo rating for new items. Defaults to 1200.
  - `maxResponses` integer, nullable — Maximum number of responses per comparison.
  - `serveResponses` integer, nullable — Number of accepted responses per rapid at which to stop serving. When set, must be less than or equal to MaxResponses. Null defaults to MaxResponses.
  - `serveToResponseRatio` number, double, nullable — Ratio of concurrent serves to max responses. When set, limits serving to avoid over-collection.
  - `serveTimeoutSeconds` integer, nullable — Time in seconds a user has to submit an answer after loading the task. When set, overrides the global default.
  - `minResponses` integer, nullable — Minimum number of responses per comparison. Defaults to 20.
  - `featureFlags` FeatureFlag[], nullable — Optional feature flags to enable for this flow.
    - `key` string, required
    - `value` string, required
  - `targetResponseCount` integer, nullable — Target average response count per completed item. Enables PID control when set.
  - `pidProportionalGain` number, double, nullable — PID proportional gain. Defaults to 0.
  - `pidIntegralGain` number, double, nullable — PID integral gain. Defaults to 0.003.
  - `pidDerivativeGain` number, double, nullable — PID derivative gain. Defaults to 0.
  - `pidOutputOffset` number, double, nullable — Constant offset added to the PID output before clamping, shifting the controller's operating point. Defaults to 25.
  - `pidMinSessionsPerMinute` integer, nullable — Minimum sessions per minute the PID can set. Defaults to 20.
  - `pidMaxSessionsPerMinute` integer, nullable — Maximum sessions per minute the PID can set. Defaults to 50.
  - `pidBatchMode` 'Total' | 'PerBatch' | 'PerBatchTimeWeighted', nullable — How PID output maps to campaign rate. Total: direct rate. PerBatch: multiplied by active batch count. PerBatchTimeWeighted: multiplied by time-weighted batch count. Defaults to Total.
  - `drainDurationSeconds` integer, nullable — Duration in seconds for draining flow items. Defaults to 40.

## Response `200`

OK

- CreateFlowEndpointOutput
  - `flowId` string, required — The ID of the created ranking flow.

## Other responses

- `400` — Bad Request
- `401` — Unauthenticated
- `403` — Forbidden

---

[API](https://skmtc.net/rapidata/apis/rapidata-api.md) · [All operations](https://skmtc.net/rapidata/apis/rapidata-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rapidata/rapidata-api/revisions/d779de93a5ee/schema)