context.call

context.call() performs an HTTP request as a workflow step, supporting longer response times up to 12 hours.

The request is executed by Upstash on your behalf, so your application does not consume compute resources during the request duration.

If the endpoint responds with a non‑success status code (anything outside 200–299), context.call() still returns the response and the workflow continues. This allows you to inspect the response (via the status field) and decide how to handle failure cases in your logic.

If you want requests to retry automatically, you can explicitly pass a retry configuration.

Arguments

url · string

The URL of the HTTP endpoint to call.

method · string

TThe HTTP method to use (GET, POST, PUT, etc.). Defaults to GET.

body · string

The request body.

headers · object

A map of headers to include in the request.

retries

Number of retry attempts if the request fails. Defaults to 0 (no retries).

retryDelay

Delay between retries (in milliseconds). By default, uses exponential backoff. You can use mathematical expressions and the special variable retried (current retry attempt count starting from 0). Examples: 1000, pow(2, retried), max(10, pow(2, retried)).

flowControl · object

Throttle outbound requests.

See Flow Control for details.

Show properties

key · string

A logical grouping key that identifies which requests share the same flow control limits.

rate · number

The maximum number of allowed requests per second.

parallelism · number

The maximum number of concurrent requests allowed.

period · string|number

The time window used to enforce the defined rate limit. Default is 1s.

timeout · number

Maximum time (in seconds) to wait for a response. If retries are enabled, this timeout applies individually to each attempt.

workflow

When using serveMany, you can call another workflow defined in the same serveMany by passing it to this parameter.

stringifyBody · string

Whether to automatically stringify the body as JSON. Defaults to true

If set to false, the body will be required to be a string and will be sent as-is.

Response

status · number

The HTTP response status code.

body · string

The response body.

context.call() attempts to parse the body as JSON. If parsing fails, the raw body string is returned.

headers · dictionary

The response headers.

In TypeScript, you can declare the expected result type for strong typing:

type ResultType = {
  field1: string,
  field2: number
};

const result = await context.call<ResultType>( ... );

Usage

TypeScript

import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<{ topic: string }>(async (context) => {
  const { userId, name } = context.requestPayload;

  const { status,  headers,  body } = await context.call("sync-user-data", {
      url: "https://my-third-party-app", // Endpoint URL
      method: "POST",
      body: {
        userId,
        name
      },
      headers: {
        authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
      },
    }
  );
});

We provide integrations for OpenAI, Anthropic, and Resend, allowing you to call their APIs with strongly typed request bodies using context.call. See context.api for details.

The context.call() function can make requests to any public API endpoint. However, it cannot:

• Make requests to localhost (unless you set up a local tunnel, here’s how)
• Make requests to internal Upstash QStash endpoints.