> ## Documentation Index
> Fetch the complete documentation index at: https://trigger-v3-fix-additional-files.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Runs

> When a [Job](/documentation/concepts/jobs) is [Triggered](/documentation/concepts/triggers), 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.

```ts
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](/documentation/concepts/tasks).
3. You can return data, which will then be retrievable with [getRun](/sdk/triggerclient/instancemethods/getrun) or the [React hooks](/documentation/guides/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](/documentation/concepts/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](/documentation/concepts/triggers) that triggered the Job.

* For [Webhooks](/documentation/concepts/triggers/webhooks) the payload is the data from the webhook.
* For [Events](/documentation/concepts/triggers/events) the payload is the data from the event, in the example above that's `{ url: "https://..." }`.
* For [Scheduled](/documentation/concepts/triggers/scheduled) the payload is an object with the timestamp and the last timestamp (previous run).

### io

The `io` object gives you access to [Integrations](/documentation/concepts/integrations) and other useful functions. [View the full reference](/sdk/io) for `io`.

A few things you can do with `io`:

* Use [Integrations](/documentation/concepts/integrations).
* Add [delays](/documentation/concepts/delays) (that can be longer than your server timeout).
* Log messages to the [Run log](/documentation/guides/viewing-runs).
* Perform [background fetch requests](/sdk/io/backgroundfetch) (that can be longer than your server timeout).
* [Send events](/documentation/concepts/triggers/events) to Trigger other Jobs.
* Create a [Task](/documentation/concepts/tasks) 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](/sdk/context) 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](/documentation/concepts/limits#concurrent-run-executions)

### 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

<CardGroup cols={2}>
  <Card title="Viewing Runs Dashboard" icon="globe" href="/documentation/guides/viewing-runs">
    View all Runs for a Job, all the way down to individual Tasks.
  </Card>

  <Card title="`io` SDK Reference" icon="wrench" href="/sdk/io">
    The `io` object gives you access to Integrations and other useful functions.
  </Card>

  <Card title="`context` SDK Reference" icon="wrench" href="/sdk/context">
    The `context` object gives you access to the current Run's context.
  </Card>
</CardGroup>