> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nelkap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggering

> Start a run of a workflow from your server code, with its payload and its tags.

Most runs start from your own code, at the moment there's work to do: a user signs up, an order comes in, someone clicks a button. Your code calls `run`, Nelkap records the run, and your code moves on without waiting for the workflow.

## Start a run

Call `run` with the workflow function and its payload:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { runId } = await nelkap.run(
  onboardUser,
  'user_42',
);
```

You pass the function itself rather than its name. TypeScript then checks the payload against the workflow's argument, and the SDK finds the name the function was registered under. The function must be one you passed to [`registerWorkflows`](https://docs.nelkap.com/reference/register-workflows).

`run` returns once Nelkap has recorded the run, with its ID. It doesn't wait for the workflow to finish, so you can call it from a request handler and answer right away.

If Nelkap turns the run down, for example because the workflow isn't registered, `run` throws a [`NelkapError`](https://docs.nelkap.com/reference/errors#nelkaperror) that names the reason.

## Payload

The payload is what the run works on. Nelkap passes it to your workflow as its only argument, on every call of the run:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export async function shipOrder(order: {
  id: string;
  address: string;
}) {
  await nelkap.step.run('label', () =>
    createShippingLabel(order.address),
  );
}

await nelkap.run(shipOrder, {
  id: 'ord_42',
  address: '1 Main St, Springfield',
});
```

* It can be any JSON value: a string, a number, an object, or a list.
* It's sent as JSON, so a `Date` reaches your workflow as a string.
* It shows on the run's page, so you can see what each run worked on.
* Its size is limited by your plan. See [Limits](https://docs.nelkap.com/limits.md#by-plan).

A workflow that needs no input takes no payload: `nelkap.run(sendDigest)`.

Keep the payload small, like an ID your workflow uses to load the rest. The run then works on the latest data, and every call carries less.

## Tags

Tags label a run, so you can find it later. Filter your runs by tag, for example to see every run of a customer:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await nelkap.run(onboardUser, 'user_42', {
  tags: ['team_7', 'beta'],
});
```

A run takes up to 10 tags, each up to 128 characters.

## Start time

A new run is pending until its turn comes. Nelkap starts pending runs every minute, so a run starts within a minute of being created, unless it waits for room under a [concurrency limit](https://docs.nelkap.com/guides/concurrency.md).

## Start a run from a workflow

A workflow can start runs of other workflows, for example one for each item of a list. Call `run` inside a step, so the new run starts once, even when the first run picks up again later:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await nelkap.step.run('invoice run', () =>
  nelkap.run(sendInvoice, orderId),
);
```

The two runs are independent: the first goes on without waiting for the second. See [Fan-out](https://docs.nelkap.com/guides/loops.md#fan-out).

## Other triggers

Your code knows exactly which workflow to start. When it doesn't, or when the work comes from somewhere else, start runs another way:

| How | When to use it |
| - | - |
| [Events](https://docs.nelkap.com/triggers/events.md) | Something happened, and any number of workflows may want to react. |
| [Schedules](https://docs.nelkap.com/triggers/schedules.md) | The work repeats at fixed times, like a weekly report. |
| [Webhooks](https://docs.nelkap.com/triggers/webhooks.md) | Another service, like a payment provider, tells you something happened. |
| [Replay](https://docs.nelkap.com/monitor/runs.md#replay-a-run) | You want to run a past run again, for example after fixing a bug. |

A workflow can use several at once, and every workflow can be started from your code, whatever else starts it.

## Trigger types

Each run shows its trigger, so you can tell how it started:

| Trigger | Started by |
| - | - |
| API | `run` |
| Event | An event emitted with `emit`, or received by a webhook. |
| Cron | A schedule. |
| Manual | A replay. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.