Test Endpoint (Streaming)

Run an iterate test for a single endpoint — issuing one request per supplied value (or value pair) — and stream the progress back over Server-Sent Events (SSE). Each iteration can optionally follow pagination, recurse through a tree of child resources, and respect rate limits. A companion GET lets a client reconnect to a running session.

POST /api/connectors/{id}/endpoints/{endpointId}/test/stream

Authorization

• Authenticated user: Required. Unauthenticated requests receive a plain 401 Unauthorized (note: error bodies on this route are plain strings or { "error": ... }, not the nested error object used elsewhere).

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Connector ID
endpointId	string	Yes	Endpoint ID

Request Body

The body is validated with Zod. iteration_params is required and comes in two shapes; everything else is optional.

Field	Type	Required	Description
iteration_params	object	Yes	The iteration plan — simple or paired (see below)
parameter_values	object	No	Base path-parameter values applied to every iteration
query_parameter_values	object	No	Base query-parameter values
custom_headers	object	No	Extra request headers
runtime_parameter_values	object	No	Values for connector runtime parameters / input variables (override baked-in static values)
body_params	object	No	Request body: { "type": "json" | "form-data" | "urlencoded" | "raw", "content": string }
endpoint_config	object	No	Inline endpoint config (id, path, method, friendly_name). Preferred over the stored endpoint so unpublished edits are honoured
recursion_config	object	No	Tree traversal per iteration: { enabled, idPath, targetParam, conditionPath?, conditionValue?, maxDepth (1–10) }
pagination_config	object	No	Follow all pages within each iteration (standard pagination config)
rate_limit_config	object	No	{ delayMs (0–60000), respectRetryAfter } — delay between iterations and HTTP 429 retry behaviour
credential_slot_id	string	No	Which stored credential slot to use (from the analyst's selection)

Simple iteration

{
  "iteration_params": {
    "param_name": "userId",
    "param_location": "path",
    "values": ["U1", "U2", "U3"]
  }
}

param_location is one of path, query, body.

Paired iteration

Iterate over (outer, inner) pairs, mapping each side to one or more parameters:

{
  "iteration_params": {
    "paired": true,
    "param_mappings": [
      { "param_name": "channelId", "param_location": "path", "paired_field": "outer" },
      { "param_name": "ts", "param_location": "query", "paired_field": "inner" }
    ],
    "pairs": [
      { "outer": "C1", "inner": "169..." },
      { "outer": "C2", "inner": "170..." }
    ]
  }
}

Response (SSE Stream)

On success the response is Content-Type: text/event-stream (with Cache-Control: no-cache). Events are emitted as event: <name> / data: <json> frames:

Event	When	Payload
session	First, immediately	{ "sessionId": string, "total": number }
counters	As pages/children are fetched	{ "pagination": number, "recursion": number }
progress	After each iteration	iteration index, total, url, statusCode, responseTimeMs, paramValue, error, responseData, recursionResult, paginationResult
rate_limit_wait	Around a delay / 429 retry	{ "reason": "retry_after" | "configured_delay", "waitDurationMs", "waitingSince" }, then null when the wait ends
stopped	The client aborted	{ "index": number, "reason": "User stopped" }
complete	At the end	{ "success", "totalTimeMs", "successCount", "failureCount", "iterationCount" }
error	On a fatal error	{ "message": string }

The stream aborts cleanly if the client disconnects (the abort cancels in-flight requests).

Example progress frame

event: progress
data: {"index":0,"total":3,"url":"https://slack.com/api/users.info?user=U1","statusCode":200,"responseTimeMs":142,"paramValue":"U1","responseData":[ ... ]}

Reconnect / Poll Session

GET /api/connectors/{id}/endpoints/{endpointId}/test/stream?sessionId={sessionId}

Returns the current state of a running or finished session (for reconnection). Requires authentication and a sessionId query parameter.

Response

{
  "sessionId": "sess_abc",
  "status": "running",
  "progress": [ ... ],
  "results": [ ... ],
  "error": null
}

Example Request

curl -N -X POST "https://api.traces.io/api/connectors/conn_slack001/endpoints/ep_user_info/test/stream" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "iteration_params": { "param_name": "userId", "param_location": "query", "values": ["U1","U2"] }
  }'

Error Responses

Error bodies on this route are plain text (or a Zod error object), not the standard nested error shape.

Status	Condition	Body
401	Not authenticated	Unauthorized
400	Invalid JSON	Invalid JSON
400	Body failed validation	{ "error": <zod format> }
400	No credentials configured	No credentials configured
400	Missing platform URL / input variables	Connector has no platform URL configured (check input variables)
400	Token exchange or auth build failed	Token exchange failed: ... / Auth error: ...
404	Connector not found	Connector not found
404	Endpoint not found	Endpoint not found
500	Failed to load credentials	Failed to retrieve credentials

On the GET (reconnect) variant: 400 Missing sessionId and 404 Session not found are also possible.