GET /v1/random/{recordType}

Request parameters

Parameter	Type	Default	Description
recordType	path string	required	The record definition name (e.g. `person`, `encounter`, `facility`).
count	query integer	`1`	Number of records to sample. Up to 10,000 for JSON; up to 10,000,000 for Avro.
seed	query integer	random	64-bit unsigned integer seed for deterministic pseudo-random sampling.
fields	query string	all	Comma-separated list of fields to include in the output.

Headers & Content Negotiation

Authorization: Bearer <SIMHEALTH_API_KEY> (Required)
Accept: application/json — Request JSON output (default when omitted or */*). Buffered up to 10,000 records.
Accept: application/avro-binary (or application/avro) — Request Avro OCF binary stream. High-throughput, streaming up to 10,000,000 records without buffering.
Accept: application/x-ndjson — Request newline-delimited JSON stream.

JSON vs. Avro Performance & Cost Tradeoffs

While JSON is the default format for rapid prototyping and easy web integration, Avro Object Container File (OCF) streaming is drastically more efficient for high-volume pipelines, automated test fixtures, and large analytical datasets:

Metric	JSON (Default)	Avro OCF (High Throughput)	Advantage
Payload Size	~1.2 KB per complex record	~220 bytes per complex record	5.5x smaller payload (reduced network egress costs)
Max Batch Volume	10,000 records (buffered in memory)	10,000,000 records (streamed chunks)	1,000x higher batch volume
Serialization Overhead	High (UTF-8 escaping, formatting)	Minimal (compact binary zigzag encoding)	4x faster draw rates
Schema Integrity	Loose dynamic structure	Self-describing embedded schema header	Zero field drift in downstream data pipelines

Network Egress & Throughput Comparison (100,000 records)

JSON (Default) 120.0 MB · $0.60 egress · 100% baseline

Avro OCF (High Throughput) 22.0 MB · $0.11 egress · 82% cost reduction

Example response

json

{
  "recordType": "person",
  "count": 1,
  "seed": 1842,
  "records": [
    {
      "person_id": "P-981742",
      "first_name": "Maria",
      "last_name": "Santos",
      "gender": "female",
      "birth_date": "1984-06-12",
      "mrn": "MRN-004928"
    }
  ]
}