call-cognite-function

Call Cognite Function

Invoke any deployed Cognite CDF Function, poll until it completes, and return a typed, schema-validated result.

Overview

The CDF Functions API uses a three-step protocol:

1. Session nonce — exchange the current user token for a short-lived nonce so the function can make authenticated API calls on the user's behalf.
2. Invoke — POST to the function's /call endpoint with your input data and the nonce.
3. Poll → fetch — GET the call status in a loop; once "Completed", GET the /response endpoint.

Every API response is validated with Zod, so schema drift surfaces as a clear ZodError at the call site instead of an undefined three layers down. The function's own output payload can also be validated against a caller-supplied schema — which doubles as the source of the return type.

Files

File	Purpose
code/cogniteFunctionService.ts	Framework-agnostic async function with Zod validation. Zero React deps. Copy into src/services/.
code/useCogniteFunction.ts	React Query (useMutation) hook wrapping the service. Copy into src/hooks/.

Dependencies: @cognite/sdk (already present in Flows/Fusion apps) and zod. The hook additionally needs @tanstack/react-query and a <QueryClientProvider> in the tree.

How to use

1. Copy the service file

callCogniteFunction<TOutput>(
  client: CogniteClient,
  functionId: string | number,
  data: unknown,
  opts?: CallCogniteFunctionOptions<TOutput>,
): Promise<TOutput>

• functionId — numeric CDF function ID (or its string form). NOT an external ID; resolve those first (see below).
• data — any JSON-serialisable object; the function receives it as its data argument.
• opts.outputSchema — the recommended way to type the result. A Zod schema for the function's response payload; the return type is inferred from it and the payload is validated at runtime. Omit it and you get unknown back (then narrow it yourself).
• opts.maxPollAttempts — default 120 (~6 min at 3 s). Increase for long-running batch jobs.
• opts.pollIntervalMs — default 3000, with ±20 % jitter to avoid thundering-herd across tabs.
• opts.signal — AbortSignal for cancellation (non-React contexts; the hook doesn't need it).