io.backgroundFetch()

io.backgroundFetch() allows you to fetch data from a URL that can take longer that the serverless timeout. The actual fetch request is performed on the Trigger.dev platform, and the response is sent back to you. An example use case is fetching data from a slow API, like some AI endpoints.

These are the docs for Trigger.dev v2 which will be deprecated on January 31st, 2025. You probably want the v3 docs.

This is used inside the OpenAI Integration for Tasks like Chat Completions Background Create

Parameters

cacheKey · string · required

Should be a stable and unique cache key inside the run(). See resumability for more information.

url · string · required

The url to fetch.

options · object

Options for the request

Hide options

method · string

The HTTP method to use for the request.

headers · object

Any headers to send with the request. Note that you can use redactString to prevent sensitive information from being stored (e.g. in the logs), like API keys and tokens.

body · string | ArrayBuffer

The body of the request.

retry options · object

An object where the key is a status code pattern and the value is a retrying strategy. Supported patterns are:

• Specific status codes: 429
• Ranges: 500-599
• Wildcards: 2xx, 3xx, 4xx, 5xx

  {
      "500-599": {
        strategy: "backoff",
        limit: 5,
        minTimeoutInMs: 1000,
        maxTimeoutInMs: 30000,
        factor: 1.8,
        randomize: true,
      },
      "429": {
        strategy: "backoff",
        limit: 10,
        minTimeoutInMs: 1000,
        maxTimeoutInMs: 60000,
        factor: 2,
        randomize: true,
      },
    }

An individual retrying strategy can be one of two types:

• backoff: Retries the request with an exponential backoff.
• headers: Retries the request using info from the response headers.

Show backoff strategy

type · backoff · required

The backoff strategy retries the request with an exponential backoff.

limit · number

The maximum number of times to retry the request.

minTimeoutInMs · number

The minimum amount of time to wait before retrying the request.

maxTimeoutInMs · number

The maximum amount of time to wait before retrying the request.

factor · number

The exponential factor to use when calculating the next retry time.

randomize · boolean

Whether to randomize the retry time.

Show headers strategy

type · headers · required

The headers strategy retries the request using info from the response headers.

limitHeader · string

The header to use to determine the maximum number of times to retry the request.

remainingHeader · string

The header to use to determine the number of remaining retries.

resetHeader · string

The header to use to determine the time when the number of remaining retries will be reset.

timeout options · object

Allows you to set timeouts for the request, as well as specific retry strategies for timeouts.

Hide options

durationInMs · number · required

The amount of time to wait before timing out the request. The minimum value is 1s and max is 2min

retry · RetryOptions

Show options

limit · number

The maximum number of times to retry the request.

minTimeoutInMs · number

The minimum amount of time to wait before retrying the request.

maxTimeoutInMs · number

The maximum amount of time to wait before retrying the request.

factor · number

The exponential factor to use when calculating the next retry time.

randomize · boolean

Whether to randomize the retry time.

Returns

A Promise that resolves with the JSON response body of the background fetch request. You can specify the type of the response body as a generic parameter.

retrying

client.defineJob({
  id: "background-fetch-job",
  name: "Background fetch Job",
  version: "0.0.1",
  trigger: eventTrigger({
    name: "example.event",
  }),
  run: async (payload, io, ctx) => {
    const response = io.backgroundFetch<CreateChatCompetionResponseData>(
      "fetch-some-data",
      "https://example.com/api/endpoint",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: redactString`Bearer ${auth.apiKey}`,
        },
        body: JSON.stringify({ foo: "bar" }),
      },
      {
        "429": {
          strategy: "headers",
          limitHeader: "x-ratelimit-limit",
          remainingHeader: "x-ratelimit-remaining",
          resetHeader: "x-ratelimit-reset",
        },
        "5xx": {
          strategy: "backoff",
          limit: 5,
          minTimeoutInMs: 1000,
          maxTimeoutInMs: 30000,
          factor: 1.8,
          randomize: true,
        },
      }
    );

    return response;
  },
});