createFailpathClient(), the run() method, the step() method, and recordStep(). Use this as a quick lookup when you need to know a type, default value, or the exact behaviour of a particular option.
If you use the generated .failpath/sdk.ts helper, these same options are available through createTypedFailpathClient(), with flow and step keys narrowed to the values in .failpath/flows.json.
createFailpathClient() options
Pass these options to createFailpathClient() when you initialise the SDK client.
string
required
Your Failpath project key. Identifies which project receives the telemetry events your application sends. Always read this from an environment variable rather than hardcoding it.
object
A plain object merged into the metadata of every event the client sends — runs, steps, and skips alike. Use it for properties that apply globally, such as environment name or service identifier.Default:
undefinedstring
default:"https://api.failpath.dev"
Overrides the URL the SDK sends events to. This option is intended for local Failpath API development only. Do not set it in production.
boolean
default:"true"
Controls whether the SDK sends any events. Set to
false to silently disable all telemetry. Wrapped functions still execute and return values normally; only the send calls are skipped. Useful in test and CI environments.boolean
default:"false"
When
true, the SDK attaches the stack trace of any caught error to the outbound error event. Keep this disabled (the default) if your errors might contain sensitive data or if stack traces are prohibitively large."background" | "await"
default:"\"background\""
Controls whether telemetry sends run in the background or block the SDK call until the send finishes.
"background" keeps instrumentation off your latency path. "await" preserves deterministic send completion for scripts, local tooling, or runtimes where background work cannot continue after the handler returns.boolean
default:"false"
When
true, the SDK throws if a telemetry send request fails. With background delivery, queued failures surface from failpath.flush(). With delivery: "await", the individual SDK call can throw. The default (false) means telemetry failures are swallowed and do not affect your application.number
default:"1500"
Maximum time, in milliseconds, to wait for each telemetry send. The SDK aborts the request after this timeout and reports the failure through
onError. Set this to 0 to disable the timeout.number
default:"1000"
Maximum number of background events to keep in memory. When the queue is full, the SDK drops new events and calls
onError if provided.(promise: Promise<void>) => void
Optional hook for edge or serverless runtimes that can keep background work alive after the request handler returns.
(err: unknown) => void
A callback invoked whenever a telemetry send request fails. Use this alongside
throwOnSendError: false to route SDK errors into your logging or alerting infrastructure without disrupting your application.Default: undefined(input: RequestInfo, init?: RequestInit) => Promise<Response>
A custom
fetch implementation. Supply this when your runtime lacks a native fetch global — for example, Node.js versions before 18 — or when you need to proxy outbound requests. The signature must match the standard fetch API.Default: globalThis.fetchfailpath.flush()
Call flush() to wait for queued background telemetry to finish sending.
flush() before a short-lived process exits, at the end of a request when your runtime does not expose waitUntil, or in tests that need deterministic event delivery. If throwOnSendError is true, flush() rejects with the first queued delivery error.
failpath.run() options
Pass these options as the second argument to failpath.run(flowKey, options).
string
A unique identifier that correlates every step belonging to the same request, job, or webhook invocation. Failpath uses this value to group steps into a single trace in the dashboard. Reuse the same
runId for every step() call within one execution.Default: auto-generatedGood sources for a runId: an HTTP request ID header, a job ID from your queue, or a webhook delivery ID from the upstream service.object
Arbitrary key/value pairs attached to this run. Merged with
defaultMetadata from the client. Use this for data that applies to the whole execution but not to every event globally — for example, the request route or the authenticated user ID.Default: undefinedrun.step() options
Pass these options as the third argument to run.step(stepKey, fn, options).
object
Arbitrary key/value pairs attached to this specific step event. Use this for data relevant only to this operation — for example, the ID of the entity being processed.Default:
undefinedfailpath.recordStep() parameters
Pass these as a single options object to failpath.recordStep(options). All four parameters are required.
string
required
The slug of the flow this step belongs to. Must match the
flow.slug value in .failpath/flows.json. With createTypedFailpathClient(), this can be typed from failpathFlows.string
required
The run ID that groups this step with others in the same execution. Use the same value you used when calling
failpath.run() for this execution.string
required
The key identifying this step within the flow. Must match the
sdkStepKey of the corresponding node in .failpath/flows.json. With createTypedFailpathClient(), this is narrowed to the valid step keys for the selected flow."running" | "success" | "error" | "skipped"
required
The status to record for this step event. Use
running when the operation begins and then success or error when it completes, use skipped for a branch that did not run, or send a terminal status directly if you are recording after the fact.