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	Something happened, and any number of workflows may react to it.	nelkap.emit, and events on each workflow.
Schedules	The work repeats at fixed times, like a weekly report.	cron on the workflow.
Webhooks	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:

app/signup.ts

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

Payload

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

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

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:

await nelkap.step.run('invoice run', () =>
  nelkap.run(sendInvoice, orderId),
);

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

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.