CALL API ENDPOINT

Raw preview. Issues one fetch through the same HTTP transport as INVOKE and returns unmodified response bodies as (_page_index INT, _raw_body STRING). No flattening, no parsing, no disk writes, no run log update. Intended for authoring and debugging.

Category: api-endpointPrivilege: adminDeltaForge extension

Syntax

CALL API ENDPOINT <name>
  [USING (<override_key> = <expr>, ...)]
  [LIMIT <n> PAGE]
  [SHOW RAW]

Description

## Overview CALL API ENDPOINT is the authoring-time companion to INVOKE. It reuses the exact HTTP transport, pagination, and URL-building pipeline, but it stops short of disk writes. The return shape is a two-column result set: - _page_index INT, zero-based page number in this call - _raw_body STRING, unmodified response body as received This is intentionally minimal: CALL is for inspecting what an API actually returns, so you can author the downstream external table's OPTIONS / flatten settings with confidence. The GUI's 'Preview' button for an API endpoint issues this statement. ## Behavior - NO writes. No per-run folder is created. No run log row is added (so SHOW API ENDPOINT RUNS will not show this call). - NO flattening or parsing. The _raw_body value is the wire response verbatim. XML stays XML. A 500 error page, if the API returned one, is surfaced as the body. - NO watermark update. Subsequent INVOKE behavior is unaffected. - Respects the same USING (...) override grammar as INVOKE, useful for testing parameter combinations before persisting them via ALTER API ENDPOINT. - LIMIT N PAGE walks the configured pagination strategy for up to N pages. If the API returns fewer pages than N, CALL simply returns what it got. ## Access Control Requires the admin role. ## Compatibility DeltaForge extension. The verb reuses SQL's CALL keyword but has no relationship to CALL stored-procedure semantics in other dialects.

Parameters

Name	Type	Description
`name`		Target endpoint as <zone>.<api>.<name>.
`overrides`		Runtime overrides, identical in shape and semantics to INVOKE's USING clause. path_param.<k> = <expr>, query_param.<k> = <expr>, or header.<K> = <expr>. Each RHS is a scalar SQL expression evaluated at CALL time. Secret-bearing keys are rejected.
`limit_pages`		Number of pages to fetch through the pagination strategy. Default 1 gives a single-page preview.

Examples

-- One-page preview of the raw wire response
CALL API ENDPOINT landing.github.issues LIMIT 1 PAGE;

-- Two pages, with a runtime parameter override
CALL API ENDPOINT landing.github.issues
  USING (query_param.state = 'closed')
  LIMIT 2 PAGE;

-- Jump directly to a specific page (most paginations still accept explicit page numbers)
CALL API ENDPOINT landing.github.issues
  USING (query_param.page = '3')
  LIMIT 1 PAGE;

Pitfalls

CALL is a PREVIEW, not a dry-run-of-INVOKE. Because it never writes, you cannot use it to 'backfill with side effects disabled' or 'rehearse a production run'. Use INVOKE against a throwaway zone or connection instead.
Runs do NOT appear in SHOW API ENDPOINT RUNS by design. If you are auditing 'who hit this endpoint', CALL usage is invisible, track it via HTTP logs if the compliance story requires it.
LIMIT N PAGE without an explicit USING override still walks pagination from page 1, which for cursor-paginated APIs means you retrieve the newest N pages. To preview deep pages, pass the cursor explicitly via USING.
The _raw_body column is a STRING, for binary response bodies it is the UTF-8 replacement-character lossy conversion. For genuinely binary endpoints, CALL is not the right tool.