io.backgroundPoll()

io.backgroundPoll() allows you to fetch data from a URL on an interval.

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

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.

interval · number · required

The interval in seconds to wait between requests. Minimum interval is 10 seconds and maximum is 5 minutes.

timeout · number · required

The timeout in seconds before aborting the polling. Minimum timeout is 30 seconds and maximum is 1 hour.

requestInit · RequestInit

Options for the fetch 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.

responseFilter · ResponseFilter

Allows you to filter the response to determine when to stop polling.

Hide options

status · string[]

An array of status codes to match against.

headers · EventFilter

An object of header key/values to match. This uses the EventFilter matching syntax

example.ts

filter: {
  header: {
    "content-type": [{ $startsWith: "application/json" }],
  },
},

body · EventFilter

An EventFilter object to match against the response body. This will only be applied if the response body is JSON.

requestTimeout · object

An optional object to specify a timeout for each individual request.

Hide options

durationInMs · number · required

The timeout in milliseconds before aborting the request.

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 matching background fetch request. You can specify the type of the response body as a generic parameter.

polling

client.defineJob({
  id: "background-poll-job",
  name: "Background Poll Job",
  version: "0.0.1",
  trigger: invokeTrigger({
    schema: z.object({ url: z.string().url() }),
  }),
  run: async (payload, io, ctx) => {
    const result = await io.backgroundPoll<{ foo: string }>("poll", {
      url: payload.url,
      interval: 10, // every 10 seconds
      timeout: 300, // stop polling after 5 minutes
      responseFilter: {
        // stop polling once this filter matches
        status: [200],
        body: {
          status: ["SUCCESS"],
        },
      },
    });
  },
});