From ed072521facb887182a1e1b46dfd157d22f098b3 Mon Sep 17 00:00:00 2001
From: Oleksandr Taruraiev <Oleksandr_Taruraiev@epam.com>
Date: Thu, 19 Mar 2026 20:27:50 +0200
Subject: [PATCH] docs(user-guide): add workflow execution tags for langfuse
 tracing

Co-Authored-By: codemie-ai <codemie.ai@gmail.com>
---
 docs/user-guide/api/index.md                  | 63 +++++++++++++++++++
 ...workflow-executions-by-tags-in-langfuse.md |  9 +++
 ...workflow-execution-for-langfuse-tracing.md | 44 +++++++++++++
 3 files changed, 116 insertions(+)
 create mode 100644 faq/can-i-filter-workflow-executions-by-tags-in-langfuse.md
 create mode 100644 faq/how-do-i-attach-tags-to-a-workflow-execution-for-langfuse-tracing.md

diff --git a/docs/user-guide/api/index.md b/docs/user-guide/api/index.md
index f78f218d..0a48920d 100644
--- a/docs/user-guide/api/index.md
+++ b/docs/user-guide/api/index.md
@@ -153,6 +153,69 @@ X-Tenant-ID: my-tenant
 
 ---
 
+## Execute Workflow
+
+Start a workflow execution programmatically via the API or SDK.
+
+### Endpoint
+
+**POST** `/v1/workflows/{workflow_id}/executions`
+
+### Request Body
+
+| Field                 | Type      | Required | Description                                                                                                   |
+| --------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| **user_input**        | String    | No       | Input text or data passed to the workflow                                                                     |
+| **tags**              | String\[] | No       | Tags attached to the Langfuse execution trace for filtering and analytics. Does not affect execution behavior |
+| **session_id**        | String    | No       | Session identifier for Langfuse tracing. Defaults to `execution_id` if not provided                           |
+| **propagate_headers** | Boolean   | No       | Forward custom `X-*` HTTP headers to MCP tool invocations                                                     |
+| **file_name**         | String    | No       | File name associated with the workflow execution                                                              |
+
+### API Example
+
+```http
+POST /v1/workflows/{workflow_id}/executions
+Content-Type: application/json
+Authorization: Bearer <your-access-token>
+
+{
+  "user_input": "Run deployment check",
+  "tags": ["experiment", "customer_X"]
+}
+```
+
+### Python SDK Example
+
+```python
+result = client.workflows.run(
+    workflow_id="<workflow-id>",
+    user_input="Run deployment check",
+    tags=["experiment", "customer_X"],
+)
+```
+
+### Node.js SDK Example
+
+`tags` is the 7th positional argument in `run()`. Pass `undefined` to skip optional arguments before it:
+
+```typescript
+const result = await client.workflows.run(
+  "<workflow-id>",
+  "Run deployment check", // userInput
+  undefined,              // fileName
+  undefined,              // sessionId
+  undefined,              // propagateHeaders
+  undefined,              // headers
+  ["experiment", "customer_X"], // tags
+);
+```
+
+:::info
+Tags appear in the Langfuse **Traces** view and can be used to filter and group executions by any label you choose, for example `"prod"`, `"nightly"`, or `"customer_X"`.
+:::
+
+---
+
 ## Success Response
 
 **Status code:** `200`
diff --git a/faq/can-i-filter-workflow-executions-by-tags-in-langfuse.md b/faq/can-i-filter-workflow-executions-by-tags-in-langfuse.md
new file mode 100644
index 00000000..78a64c2e
--- /dev/null
+++ b/faq/can-i-filter-workflow-executions-by-tags-in-langfuse.md
@@ -0,0 +1,9 @@
+# Can I filter workflow executions by tags in Langfuse?
+
+Yes. Once a workflow execution completes, its tags appear in the Langfuse UI under **Traces**. Use the **Tags** filter to find executions by one or more tags — only traces that carry all specified tags are returned.
+
+Tags must be passed at execution time via the API `tags` field or the SDK `tags` parameter. They cannot be added to an execution after it has started.
+
+## Sources
+
+- [Execute Workflow](https://codemie-ai.github.io/docs/user-guide/api/#execute-workflow)
diff --git a/faq/how-do-i-attach-tags-to-a-workflow-execution-for-langfuse-tracing.md b/faq/how-do-i-attach-tags-to-a-workflow-execution-for-langfuse-tracing.md
new file mode 100644
index 00000000..41252b7e
--- /dev/null
+++ b/faq/how-do-i-attach-tags-to-a-workflow-execution-for-langfuse-tracing.md
@@ -0,0 +1,44 @@
+# How do I attach tags to a workflow execution for Langfuse tracing?
+
+Pass a `tags` array in the execution request. Tags are attached to the Langfuse trace for that run and have no effect on execution behavior.
+
+**API:**
+
+```http
+POST /v1/workflows/{workflow_id}/executions
+Content-Type: application/json
+Authorization: Bearer <your-access-token>
+
+{
+  "user_input": "Run deployment check",
+  "tags": ["experiment", "customer_X"]
+}
+```
+
+**Python SDK:**
+
+```python
+result = client.workflows.run(
+    workflow_id="<workflow-id>",
+    user_input="Run deployment check",
+    tags=["experiment", "customer_X"],
+)
+```
+
+**Node.js SDK** (`tags` is the 7th positional argument):
+
+```typescript
+const result = await client.workflows.run(
+  "<workflow-id>",
+  "Run deployment check", // userInput
+  undefined,              // fileName
+  undefined,              // sessionId
+  undefined,              // propagateHeaders
+  undefined,              // headers
+  ["experiment", "customer_X"], // tags
+);
+```
+
+## Sources
+
+- [Execute Workflow](https://codemie-ai.github.io/docs/user-guide/api/#execute-workflow)