Seeded weighted sample API

Draws n distinct items without replacement with probability proportional to weight, using the Efraimidis-Spirakis A-Res reservoir algorithm. The value-add: correct weighted sampling without replacement (the naive approach is biased) and reproducible from the seed. Answers 'How do I sample weighted items without replacement?', 'Give me a reproducible weighted subset.'.

Price$0.02per request

MethodPOST

Route/v1/generate/weighted-sample

StatusLive

MIME typeapplication/json

Rate limit120/minute

Cache0s public

weightedsamplewithout-replacementefraimidis-spirakisdeterministicseedsamplinggenerate

API URLhttps://x402.hexl.dev/v1/generate/weighted-sample

Integration docs

Example request

{
  "items": [
    {
      "value": "a",
      "weight": 1
    },
    {
      "value": "b",
      "weight": 5
    },
    {
      "value": "c",
      "weight": 1
    }
  ],
  "n": 2,
  "seed": "abc"
}

Example response

{
  "sample": [
    "b",
    "a"
  ],
  "n": 2,
  "fromTotal": 3,
  "seed": "abc",
  "algorithm": "Efraimidis-Spirakis A-Res",
  "deterministic": true,
  "interpretation": "2 items sampled without replacement, probability proportional to weight."
}

Input schema

{
  "type": "object",
  "required": [
    "items",
    "n",
    "seed"
  ],
  "properties": {
    "items": {
      "type": "array",
      "examples": [
        [
          {
            "value": "a",
            "weight": 1
          },
          {
            "value": "b",
            "weight": 5
          },
          {
            "value": "c",
            "weight": 1
          }
        ]
      ]
    },
    "n": {
      "type": "integer",
      "minimum": 1,
      "examples": [
        2
      ]
    },
    "seed": {
      "type": [
        "string",
        "number"
      ],
      "examples": [
        "abc"
      ]
    }
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}