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:

​
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.