Fluency Workflow Telemetry API

Send completed automated workflow executions to Fluency so they can be analyzed beside human executions of the same process. The TypeScript and Python SDKs are the recommended integration because they create IDs, measure timings, preserve failures, retry delivery, and enforce payload limits. Use this HTTP API when your runtime cannot use either SDK or when you are building a custom adapter. For SDK installation and integration examples, see Fluency AI Agent SDKs.

This is not meant to replace services like BrainTrust, LangTrace, and similar. This is taking telemetry from the business perspective, allowing you to optimize, manage, improve, and measure work against the broader business context.

Base URL

Fluency supplies the endpoint for your organization’s home region during onboarding.

Region	Base URL
Australia	`https://ap-southeast-2.wb.usefluency.com`
United States	`https://us-east-1.wb.usefluency.com`
Singapore	Supplied during onboarding
Hong Kong	Supplied during onboarding

Store this as FLUENCY_WORKFLOW_ENDPOINT. Do not copy a URL from another Fluency organization or choose a region based on latency; an organization’s data remains in its assigned region.

FLUENCY_WORKFLOW_TELEMETRY_ENDPOINT is an internal Fluency Server setting. Customer workflows use FLUENCY_WORKFLOW_ENDPOINT.

Authentication

Send the organization-owned API key supplied by Fluency as a bearer credential:

Authorization: Bearer YOUR_FLUENCY_WORKFLOW_API_KEY
Content-Type: application/json

The key must:

be owned by your Fluency organization;
include the workflow-telemetry:write permission; and
belong to an organization enabled for workflow telemetry.

The verified key determines the organization. Do not send an organization ID in the body, query string, or a custom header. Store the key in your secret manager. Use separate keys for workflows or deployments that need independent audit history, rotation, or revocation. Never include the key in prompts, step input/output, artifacts, logs, or source control.

Submit a run

POST /ext/workflow-telemetry/runs

The endpoint accepts one completed or failed workflow execution. Acceptance is durable, but process association and artifact reconciliation continue asynchronously.

Minimal request

curl --request POST \
  "$FLUENCY_WORKFLOW_ENDPOINT/ext/workflow-telemetry/runs" \
  --header "Authorization: Bearer $FLUENCY_WORKFLOW_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "run_id": "invoice-job-018f6f6e",
    "executor": {
      "type": "automation",
      "id": "accounts-payable-workflow",
      "name": "Accounts payable workflow",
      "version": "2026.09"
    },
    "name": "Process supplier invoice",
    "started_at": "2026-09-19T20:00:00Z",
    "ended_at": "2026-09-19T20:00:08Z",
    "status": "completed",
    "steps": [],
    "artifacts": [],
    "metadata": {}
  }'

Complete request

{
  "run_id": "invoice-job-018f6f6e",
  "executor": {
    "type": "automation",
    "id": "accounts-payable-workflow",
    "name": "Accounts payable workflow",
    "version": "2026.09"
  },
  "name": "Process supplier invoice",
  "started_at": "2026-09-19T20:00:00Z",
  "ended_at": "2026-09-19T20:00:08Z",
  "status": "completed",
  "steps": [
    {
      "step_id": "read-invoice",
      "name": "Read invoice",
      "kind": "tool",
      "started_at": "2026-09-19T20:00:00Z",
      "ended_at": "2026-09-19T20:00:02Z",
      "status": "completed",
      "input": {
        "document_uri": "https://documents.example.com/invoices/INV-123"
      },
      "output": {
        "invoice_number": "INV-123",
        "total": 1250.0,
        "currency": "AUD"
      },
      "error": null
    },
    {
      "step_id": "approve-invoice",
      "name": "Approve invoice",
      "kind": "llm",
      "started_at": "2026-09-19T20:00:02Z",
      "ended_at": "2026-09-19T20:00:08Z",
      "status": "completed",
      "input": {
        "invoice_number": "INV-123"
      },
      "output": {
        "decision": "approved"
      },
      "error": null
    }
  ],
  "artifacts": [
    {
      "artifact_id": "invoice-job-018f6f6e-result",
      "name": "Invoice INV-123 approval",
      "kind": "invoice-decision",
      "uri": null,
      "content": {
        "invoice_number": "INV-123",
        "decision": "approved"
      },
      "business_artifact": {
        "source": "erp:production:invoices",
        "external_id": "INV-123"
      }
    }
  ],
  "metadata": {
    "environment": "production",
    "queue": "accounts-payable"
  }
}

Run fields

Field	Type	Required	Description
`run_id`	string	Yes	Stable execution identifier, 1–200 characters. Reuse it only to retry the same evidence.
`executor`	object	Yes	Stable executor identity and type displayed for the automated actor.
`name`	string	Yes	Descriptive workflow name, 1–500 characters. Fluency uses it as process-matching evidence.
`started_at`	RFC 3339 timestamp	Yes	Timezone-aware start of the complete workflow execution.
`ended_at`	RFC 3339 timestamp	Yes	Timezone-aware end of the execution. Must be on or after `started_at`.
`status`	string	Yes	`completed` or `failed`. Running or partial executions are not accepted.
`steps`	array	Yes	Zero to 1,000 measured steps. Step IDs must be unique within the run.
`artifacts`	array	Yes	Zero to 100 execution artifacts. Artifact IDs must be unique within the run.
`process_id`	string	No	Exact existing Fluency process ID. Most customer integrations omit this and let Fluency match or create the process.
`metadata`	object	No	JSON-compatible customer metadata. Defaults to `{}`.

Unknown fields are rejected.

Executor fields

Field	Type	Required	Description
`type`	string	Yes	`agent`, `automation`, or `service`. This controls the actor label shown in Fluency.
`id`	string	Yes	Stable workflow identity, 1–200 characters. Keep it constant across executions and deployments of the same workflow.
`name`	string	Yes	Customer-facing workflow name, 1–500 characters.
`version`	string or `null`	No	Your workflow, model, or deployment version.

For the organization API key flow, the submitted executor identity describes the workflow while the verified credential independently determines the organization and authorization.

Step fields

Field	Type	Required	Description
`step_id`	string	Yes	Unique identifier within the run, 1–200 characters.
`name`	string	Yes	Meaningful customer-facing step name, 1–500 characters.
`kind`	string	Yes	`tool`, `llm`, `step`, or `log`.
`started_at`	RFC 3339 timestamp	Yes	Timezone-aware start within the parent run interval.
`ended_at`	RFC 3339 timestamp	Yes	Timezone-aware end within the run and on or after the step start.
`status`	string	Yes	`completed` or `failed`.
`input`	any JSON value	No	Input used by the step.
`output`	any JSON value	No	Output produced by the step.
`error`	string or `null`	No	Error message for a failed step.

Steps may overlap or nest. Fluency calculates handling time from the union of measured step intervals so concurrent work is not counted twice.

Artifact fields

Field	Type	Required	Description
`artifact_id`	string	Yes	Unique evidence identifier within the run, 1–200 characters.
`name`	string	Yes	Customer-facing artifact name, 1–500 characters.
`kind`	string	Yes	Customer-defined artifact category, 1–200 characters.
`uri`	string or `null`	No	Reference to the source object. Fluency stores the reference and does not fetch arbitrary remote files.
`content`	any JSON value	No	Snapshot or structured result to retain as execution evidence.
`business_artifact`	object	No	Stable identity that connects this evidence to the same invoice, ticket, claim, case, order, or other object handled by people or automated workflows.

An execution artifact records what this particular run produced or observed. A business artifact identifies the underlying object across many human and automated executions.

Business artifact identity

Use one of these forms: Known Fluency artifact ID:

{
  "id": "existing-fluency-artifact-id"
}

Namespaced source-system identity:

{
  "source": "erp:production:invoices",
  "external_id": "INV-123"
}

{
  "id": "existing-fluency-artifact-id",
  "source": "erp:production:invoices",
  "external_id": "INV-123"
}

source and external_id must be supplied together. Make source specific enough to separate systems, environments, accounts, and record types. Display names are not stable identity. If no explicit business identity is supplied, Fluency may use exact structured identifiers and tenant-local semantic evidence. Ambiguous or conflicting evidence remains unlinked rather than merging unrelated objects.

Limits and validation

Maximum request body: 2 MiB.
Maximum steps: 1,000.
Maximum artifacts: 100.
Run, step, and artifact timestamps must be timezone-aware and ordered.
Every step interval must fall within the run interval.
Completed or failed runs cannot contain running steps.
IDs must be unique within the run.
All values must be valid JSON.

The SDK applies a smaller default snapshot limit of 1 MiB so it can reject oversized evidence before delivery.

Acceptance response

New evidence:

{
  "run_id": "invoice-job-018f6f6e",
  "status": "accepted"
}

An identical retry:

{
  "run_id": "invoice-job-018f6f6e",
  "status": "duplicate"
}

Both responses use HTTP 200. accepted means Fluency durably stored the evidence. It does not mean asynchronous process matching has finished.

Check processing status

GET /ext/workflow-telemetry/runs/{run_id}

curl \
  "$FLUENCY_WORKFLOW_ENDPOINT/ext/workflow-telemetry/runs/invoice-job-018f6f6e" \
  --header "Authorization: Bearer $FLUENCY_WORKFLOW_API_KEY"

Example response:

{
  "run_id": "invoice-job-018f6f6e",
  "processing_status": "ready",
  "process_id": "process_01JZ8E4M5A",
  "processing_error": null,
  "projection": {
    "description": "Reads, validates, and approves a supplier invoice.",
    "association": {
      "method": "semantic",
      "reason": "The measured steps align with the existing invoice process.",
      "confidence": 0.93
    }
  }
}

Status	Meaning
`pending`	Stored and waiting for processing, or waiting for an automatic retry.
`processing`	A worker is matching the process and reconciling artifacts.
`ready`	Projection succeeded and the execution can appear in the product.
`failed`	Processing exhausted its automatic retries. Raw evidence remains stored.

process_id can be null until association succeeds. projection contains enrichment details and may gain fields during the private preview; clients should use processing_status and process_id for control flow. An organization API key can check runs submitted to its organization.

Idempotency and retries

run_id is the idempotency key across the organization.

Retry the exact same payload with the same run_id after a timeout or temporary server error.
An identical payload returns duplicate and does not create another execution.
Different evidence under an existing run_id returns HTTP 409.
Use a new run_id for every distinct execution, including a business-level retry that actually ran the workflow again.

Use exponential backoff with jitter for network errors and HTTP 5xx responses. Do not automatically retry other 4xx responses without correcting the request or credential.

Errors

Errors return a JSON body with a human-readable detail field.

HTTP status	Meaning	Typical action
`400`	Invalid body, timestamp, status, interval, ID, or business artifact reference.	Correct the evidence before retrying.
`401`	Missing, malformed, invalid, expired, or wrong-owner credential.	Replace or refresh the credential.
`403`	Missing `workflow-telemetry:write`, or the organization is not enabled.	Ask the Fluency administrator to check access.
`404`	Explicit process, artifact, or requested run does not exist in the authenticated organization.	Correct the identifier or omit optional explicit association.
`409`	Existing run ID has different evidence, or business artifact identifiers conflict.	Use the original evidence or a new run ID; reconcile artifact identity.
`413`	Request exceeds 2 MiB.	Reduce captured content or use SDK metadata-only mode.
`5xx`	Temporary Fluency, authentication-provider, or database failure.	Retry with exponential backoff and jitter.

Never log the bearer credential while recording or reporting an error.

Process matching

Most customers should omit process_id. Fluency attempts association in this order:

An explicit valid process_id, when supplied.
A unique normalized workflow-name match.
Grounded semantic matching against candidate processes in the authenticated organization.
Creation or reuse of a workflow process when no safe existing match is available.

Fluency does not attach a run to a process when the evidence is uncertain. A matched human process keeps its existing process ID, allowing human and automated executions to appear together.

Delivery and privacy

The API accepts final snapshots, not live partial updates or arbitrary OTLP streams.
Inputs, outputs, artifact content, URIs, and error messages are stored when supplied.
Do not include credentials or secrets in captured evidence.
Omit sensitive values or use the SDK’s captureContent: false / capture_content=False mode.
Processing failures do not delete the raw accepted evidence.
The current API does not provide a customer endpoint for deleting individual runs.

SDK equivalents

TypeScript:

import { init } from '@fluency/workflow-telemetry';

const fluency = init({
  endpoint: process.env.FLUENCY_WORKFLOW_ENDPOINT!,
  executor: { type: 'automation', id: 'accounts-payable-workflow', name: 'Accounts payable workflow' },
});

await fluency.run('Process supplier invoice', async (run) => {
  await run.step('Approve invoice', approveInvoice, { kind: 'tool' });
});

await fluency.shutdown();

Python:

from fluency_workflow_telemetry import init

fluency = init(
  endpoint=os.environ["FLUENCY_WORKFLOW_ENDPOINT"],
  executor={"type": "automation", "id": "accounts-payable-workflow", "name": "Accounts payable workflow"},
)

with fluency.run("Process supplier invoice") as run:
  with run.step("Approve invoice", kind="tool") as step:
    step.output = approve_invoice()

fluency.shutdown()

See Fluency AI Agent SDKs for installation, LangChain callbacks, OpenTelemetry adapters, delivery guarantees, and release-package verification.

Support information

When contacting Fluency, provide:

Fluency organization name;
executor.id;
run_id;
approximate UTC timestamp;
endpoint region;
SDK language and version, if applicable; and
HTTP status and error detail.

Never send the API key.

Getting Started

IT Setup

Admin Setup

Work Explorer

Opportunities

SDKs

MCP

Product Updates

Fluency Workflow Telemetry API

Base URL

Authentication

Submit a run

Minimal request

Complete request

Run fields

Executor fields

Step fields

Artifact fields

Business artifact identity

Limits and validation

Acceptance response

Check processing status

Idempotency and retries

Errors

Process matching

Delivery and privacy

SDK equivalents

Support information

​Base URL

​Authentication

​Submit a run

​Minimal request

​Complete request

​Run fields

​Executor fields

​Step fields

​Artifact fields

​Business artifact identity

​Limits and validation

​Acceptance response

​Check processing status

​Idempotency and retries

​Errors

​Process matching

​Delivery and privacy

​SDK equivalents

​Support information

Base URL

Authentication

Submit a run

Minimal request

Complete request

Run fields

Executor fields

Step fields

Artifact fields

Business artifact identity

Limits and validation

Acceptance response

Check processing status

Idempotency and retries

Errors

Process matching

Delivery and privacy

SDK equivalents

Support information