Runs

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