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

> The four ways to start a run, and how to start one from your code with nelkap.run.

A run starts in one of four ways. A workflow can use several of them at once, and every workflow can be started from your code, whatever else starts it.

| Trigger | Use it when | How |
| - | - | - |
| Your code | Your code knows exactly which workflow to start, like onboarding right after a sign-up. | `nelkap.run`, on this page. |
| [Events](https://docs.nelkap.com/triggers/events.md) | Something happened, and any number of workflows may react to it. | `nelkap.emit`, and `events` on each workflow. |
| [Schedules](https://docs.nelkap.com/triggers/schedules.md) | The work repeats at fixed times, like a weekly report. | `cron` on the workflow. |
| [Webhooks](https://docs.nelkap.com/triggers/webhooks.md) | Another service, like a payment provider, calls a URL when something happens. | A webhook created in the console. |

## Start a run

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

```ts app/signup.ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { nelkap, onboardUser } from '../nelkap';
import { createUser } from './users';

export async function signUp(email: string) {
  const user = await createUser(email);

  const { runId } = await nelkap.run(onboardUser, user.id);

  return { user: user, runId: runId };
}
```

* You pass the function itself, not its name. The SDK finds the name it was registered under, and TypeScript checks the payload against the workflow's argument.
* The function must be one you passed to [`registerWorkflows`](https://docs.nelkap.com/concepts/workflows#register-workflows). Any other function throws an error.
* `run` returns as soon as Nelkap has recorded the run, with its ID. It doesn't wait for the workflow to finish, so a request handler can answer right away.

The run then starts within a minute. See [Lifecycle](https://docs.nelkap.com/concepts/runs.md#lifecycle).

## Payload

The payload is the argument your workflow receives. Its type comes from the workflow's signature:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
type Order = {
  id: string;
  address: string;
};

export async function shipOrder(order: Order) {
  await nelkap.step.run('label', () =>
    createLabel(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 an array. A workflow that takes no argument is started without a payload: `nelkap.run(sendDigest)`. See [Payload](https://docs.nelkap.com/concepts/runs.md#payload) for its size limit and how it's sent.

## Tags

Tags label the run, so you can filter runs by them in the console, 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 a run from a workflow

A workflow can start runs of other workflows, for example one for each item of a list. Start them inside a step:

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

> [!WARNING]
>
> Outside a step, `nelkap.run` runs again on every call of the workflow, and starts a new run each time. Inside a step, the run starts once, and the step's saved result keeps its ID.

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

## Many runs at once

Each call to `nelkap.run` is one request to Nelkap, and your plan sets how many requests your workspace can make per second: 50, 500, or 1,000. Above that, `run` throws a `NelkapError` with the code `throughputLimitReached`.

To start thousands of runs, don't loop over `nelkap.run` in a request handler. Start one run that lists the items and starts a run per item, each in its own step, as in [Fan-out](https://docs.nelkap.com/guides/loops.md#fan-out). The steps run one after the other, and a start turned down for `throughputLimitReached` fails only its own step: catch it, sleep, and try again, as in [Retries](https://docs.nelkap.com/guides/failures.md#retries).

## Errors

| Error | When |
| - | - |
| `Error` | The function wasn't passed to `registerWorkflows`. |
| `NelkapError` `workflowNotFound` | The project has no enabled workflow with this name. It may not be registered yet in this environment. |
| `NelkapError` `badRequest` | The payload or a tag breaks a limit. `issues` says which. |
| `NelkapError` `payloadLimitReached` | The payload is larger than your plan allows. |
| `NelkapError` `throughputLimitReached` | Your workspace made more requests this second than your plan allows. |

Every code is described in [Errors](https://docs.nelkap.com/reference/errors.md#api-errors).


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