Skip to main content

Benchmarks API

Access category-level financial performance benchmarks. All benchmark endpoints require the benchmarks:read scope.

Base path: https://api.valcr.site/data/v1

GET /benchmarks​

Returns aggregate benchmark percentiles for a given category and optional segment.

Request​

GET /benchmarks?category=ecommerce&segment=fashion&period=2024-Q4
Authorization: Bearer vcr_live_your_key

Parameters​

ParameterTypeRequiredDescription
categorystring✓Market category
segmentstring—Sub-segment filter
periodstring—Time period (default: latest quarter)

Supported categories: ecommerce, saas, marketplace, retail, fintech, food_beverage, health_wellness

Response 200​

{
  "category":     "ecommerce",
  "segment":      "fashion",
  "period":       "2024-Q4",
  "generated_at": "2025-01-14T08:00:00Z",
  "sample_size":  1842,
  "metrics": {
    "gross_margin": {
      "p10": 0.18, "p25": 0.31, "p50": 0.44,
      "p75": 0.59, "p90": 0.68, "mean": 0.43
    },
    "revenue_growth": {
      "p10": -0.02, "p25": 0.06, "p50": 0.14,
      "p75": 0.28, "p90": 0.51, "mean": 0.15
    },
    "customer_ltv": {
      "p10": 42, "p25": 98, "p50": 188,
      "p75": 340, "p90": 620, "mean": 210
    },
    "cart_abandon_rate": {
      "p10": 0.51, "p25": 0.60, "p50": 0.69,
      "p75": 0.77, "p90": 0.84, "mean": 0.69
    },
    "average_order_value": {
      "p10": 28, "p25": 52, "p50": 87,
      "p75": 148, "p90": 240, "mean": 94
    },
    "refund_rate": {
      "p10": 0.02, "p25": 0.04, "p50": 0.07,
      "p75": 0.12, "p90": 0.19, "mean": 0.08
    }
  }
}

Available metrics by category​

MetricKeyCategories
Gross margingross_marginAll
Revenue growth (QoQ)revenue_growthAll
Net revenue retentionnet_revenue_retentionSaaS, Marketplace
Customer LTVcustomer_ltvAll
CACcustomer_acquisition_costAll
LTV:CAC ratioltv_cac_ratioAll
Churn ratechurn_rateSaaS
Cart abandonmentcart_abandon_rateEcommerce, Marketplace
Average order valueaverage_order_valueEcommerce, Retail
Refund raterefund_rateEcommerce, Retail
Repeat purchase raterepeat_purchase_rateEcommerce, Retail, F&B
GMV growthgmv_growthMarketplace
Take ratetake_rateMarketplace
Burn multipleburn_multipleSaaS, Fintech

GET /benchmarks/percentile​

Returns the percentile rank of a specific metric value within a category.

Request​

GET /benchmarks/percentile?metric=gross_margin&value=0.52&category=ecommerce
Authorization: Bearer vcr_live_your_key

Parameters​

ParameterTypeRequiredDescription
metricstring✓Metric key (see table above)
valuefloat✓The value to rank
categorystring✓Market category
segmentstring—Optional segment filter
periodstring—Period (default: latest)

Response 200​

{
  "metric":      "gross_margin",
  "value":       0.52,
  "category":    "ecommerce",
  "period":      "2024-Q4",
  "percentile":  71.4,
  "interpretation": "This gross margin places the merchant in the top 28.6% of ecommerce operators.",
  "context": {
    "p50":  0.44,
    "p75":  0.59,
    "p90":  0.68
  }
}

Python example​

import requests

r = requests.get(
    "https://api.valcr.site/data/v1/benchmarks/percentile",
    headers={"Authorization": "Bearer vcr_live_your_key"},
    params={
        "metric":   "gross_margin",
        "value":    0.52,
        "category": "ecommerce",
    },
)
result = r.json()
print(f"Gross margin of 52% is at the {result['percentile']:.0f}th percentile")
# → Gross margin of 52% is at the 71st percentile

GET /benchmarks/distribution​

Returns the full distribution histogram for a metric, useful for charting.

Request​

GET /benchmarks/distribution?metric=gross_margin&category=ecommerce&buckets=20
Authorization: Bearer vcr_live_your_key

Parameters​

ParameterTypeRequiredDescription
metricstring✓Metric key
categorystring✓Market category
bucketsinteger—Number of histogram buckets (default: 20, max: 100)
segmentstring—Optional segment filter

Response 200​

{
  "metric":   "gross_margin",
  "category": "ecommerce",
  "period":   "2024-Q4",
  "histogram": [
    { "bucket_start": 0.00, "bucket_end": 0.05, "count": 24,  "pct": 1.3 },
    { "bucket_start": 0.05, "bucket_end": 0.10, "count": 58,  "pct": 3.1 },
    { "bucket_start": 0.10, "bucket_end": 0.15, "count": 112, "pct": 6.1 },
    { "bucket_start": 0.15, "bucket_end": 0.20, "count": 187, "pct": 10.2 },
    ...
  ],
  "sample_size": 1842,
  "stats": {
    "min": -0.12, "max": 0.91,
    "mean": 0.43, "std_dev": 0.14
  }
}

GET /benchmarks/history​

Returns benchmark values over multiple time periods, enabling trend analysis.

Request​

GET /benchmarks/history?metric=gross_margin&category=ecommerce&periods=8
Authorization: Bearer vcr_live_your_key

Parameters​

ParameterTypeRequiredDescription
metricstring✓Metric key
categorystring✓Market category
periodsinteger—Number of periods to return (default: 4, max: 20)
granularitystring—quarterly (default) or monthly
segmentstring—Optional segment

Response 200​

{
  "metric":      "gross_margin",
  "category":    "ecommerce",
  "granularity": "quarterly",
  "history": [
    {
      "period": "2023-Q1",
      "p25": 0.29, "p50": 0.42, "p75": 0.57,
      "sample_size": 1502
    },
    {
      "period": "2023-Q2",
      "p25": 0.30, "p50": 0.43, "p75": 0.57,
      "sample_size": 1611
    },
    {
      "period": "2023-Q3",
      "p25": 0.30, "p50": 0.43, "p75": 0.58,
      "sample_size": 1688
    },
    {
      "period": "2023-Q4",
      "p25": 0.31, "p50": 0.44, "p75": 0.58,
      "sample_size": 1731
    }
  ]
}

Error responses​

Missing scope​

{
  "detail": "Scope 'benchmarks:read' required for this endpoint",
  "code":   "auth.insufficient_scope",
  "status": 403
}

Invalid category​

{
  "detail": "Category 'widgets' is not supported. Valid values: ecommerce, saas, marketplace, retail, fintech, food_beverage, health_wellness",
  "code":   "validation.invalid_category",
  "status": 422
}
Last updated on