Request Aggregation

Fan out a single client request to multiple upstream APIs in parallel, then merge the results into one response. Eliminate client-side orchestration and reduce round trips.

Quickstart

Add an aggregation block to your route to specify the upstream APIs to call. Each API responds concurrently and the results are combined.

{
  "aggregation": {
    "mergeStrategy": "keyed",
    "timeoutMs": 5000,
    "calls": [
      {
        "key": "user",
        "url": "https://users-api.example.com/me",
        "method": "GET",
        "required": true
      },
      {
        "key": "orders",
        "url": "https://orders-api.example.com/recent",
        "method": "GET",
        "required": false
      }
    ]
  }
}

Reference

Field	Type	Default	Required	Description
mergeStrategy	"keyed" \| "merge"	"keyed"	No	How the JSON responses from upstream are combined.
timeoutMs	integer	5000	No	Global timeout in milliseconds for all upstream calls to complete.
calls.key	string	-	Yes	The JSON key associated with this upstream call.
calls.url	string (URI)	-	Yes	The full URL of the upstream to call. Private IPs are rejected.
calls.required	boolean	false	No	If true, the entire aggregation request fails if this upstream fails. If false, the key returns `null`.

Examples

Types of Merge Strategies

keyed

Each upstream result is nested under its key. Failed optional calls return null for their key.

{ "user": {...}, "orders": [...], "notifications": null }

merge

All upstream results are shallow-merged into a single flat object. Later keys override earlier ones on conflict.

{ "id": 1, "name": "Alice", "orders": [...] }

Common Errors

502 Bad Gateway

Required Call Failed

Fix: One of your upstream calls with "required": true returned a non-2xx status code or was unreachable. Either ensure the upstream is highly available or set required to false.

504 Gateway Timeout

Aggregation Timeout Exceeded

Fix: The total parallel execution time exceeded the configured timeoutMs (or default 5s). Increase the timeout or optimize the slowest upstream.

Plan Requirements

Request Aggregation is available on higher-tier plans.