Runs

When a Job is Triggered, the Run function is called.

Everytime a Job is triggered, a Run is created with a payload of data.

Anatomy of a Run

A Run is a record of the execution of a Job. It is created from run() function of a Job.

client.defineJob({
  id: "event-1",
  name: "Run when the foo.bar event happens",
  version: "0.0.1",
  trigger: eventTrigger({
    name: "foo.bar",
    schema: z.object({
      url: z.string(),
    }),
  }),
  // 1. Run function with params
  run: async (payload, io, ctx) => {
    // 2. Regular code and Tasks
    // 3. Optionally return data from run execution
    return { status: "success" };
  },
});

1. The run() function is called with some useful parameters. More on that in a second.
2. Inside the run function you can write regular code and use Tasks.
3. You can return data, which will then be retrievable with getRun or the React hooks.

Resumability

Runs can exceed the maximum timeout on serverless platforms. If a Run exceeds this limit, it will be re-run. When it is re-run, any completed Tasks return their original output and they aren’t re-run. Read more about Resumability.

Run function parameters

payload

The payload is the data that triggered the Job. It is the same data that was sent to the Trigger that triggered the Job.

• For Webhooks the payload is the data from the webhook.
• For Events the payload is the data from the event, in the example above that’s { url: "https://..." }.
• For Scheduled the payload is an object with the timestamp and the last timestamp (previous run).

io

The io object gives you access to Integrations and other useful functions. View the full reference for io.

A few things you can do with io:

• Use Integrations.
• Add delays (that can be longer than your server timeout).
• Log messages to the Run log.
• Perform background fetch requests (that can be longer than your server timeout).
• Send events to Trigger other Jobs.
• Create a Task manually by wrapping code in io.runTask.

context

The context object gives you access to information about the current Run, Job, Environment, Organization and Event. View the full reference for context.

Run Statuses

Pending

The run has been created but has not started yet. This is the initial status of a run.

Queued

The run is waiting to be executed. Runs can be queued because of Run Execution Concurrency Limits

Waiting on Connections

If a run depends on a hosted integration, it will be in this status until the integration is ready.

Executing

The run is currently executing. This means that the run function is running.

Waiting

The run is waiting, either because of a call to io.wait() or because a task failed and will be retried at some point in the future. Runs in this state don’t count towards concurrency limits.

Failed

The run failed. This can happen if the run function throws an error or if a task fails and the run is not configured to retry.

Completed

The run completed successfully. This means that the run function finished executing and all tasks completed successfully.

Cancelled

The run was cancelled. This can happen if the run is cancelled manually.

Timed Out

The run timed out. This can happen if the run exceeds the maximum run duration, or if we receive a serverless function execution timed out response when hitting your endpoint repeatedly with no new task creation.

Invalid Payload

The run failed because the payload was invalid.

Unresolved Auth

The run failed because the auth data could not be resolved when using a custom Auth Resolver.

References

Viewing Runs Dashboard

View all Runs for a Job, all the way down to individual Tasks.

`io` SDK Reference

The io object gives you access to Integrations and other useful functions.

`context` SDK Reference

The context object gives you access to the current Run’s context.