# Get log (/api-reference/logs/getLog)

`GET /api/v2/logs/{runId}`

Get a run's workflow graph, trace spans, final output, and cost. Trace spans expire separately, so an empty `traceSpans` array does not prove none were recorded. Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup. Workspace folder trees exceeding 10,000 folders return `413`.

OAuth scope: `api:read`.

## Authentication

```json

{
  "requirements": [
    {
      "apiKey": []
    },
    {
      "oauthBearer": [
        "api:read"
      ]
    }
  ],
  "schemes": {
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key",
      "description": "Send a personal or workspace API key in `X-API-Key`. See [key types and access](https://docs.sim.ai/api-reference/authentication#key-types); operations that reject workspace keys say so in their description."
    },
    "oauthBearer": {
      "type": "oauth2",
      "description": "Send a Sim OAuth access token in `Authorization: Bearer`. See [OAuth authentication and scopes](https://docs.sim.ai/api-reference/authentication#oauth-access-tokens).",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
          "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
          "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
          "scopes": {
            "api:read": "Read your workspaces, workflows, files, tables, and logs",
            "api:write": "Read, create, change, run, and delete resources in your workspaces",
            "offline_access": "Stay signed in without asking again"
          }
        }
      }
    }
  }
}

```

Required OAuth scope: `api:read`.

## Request examples

### cURL

```bash
curl --request GET 'https://www.sim.ai/api/v2/logs/string' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### JavaScript

```javascript
const response = await fetch("https://www.sim.ai/api/v2/logs/string", {
  "method": "GET",
  "headers": {
    "X-API-Key": "YOUR_API_KEY"
  }
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
```

### Python

```python
import requests

response = requests.request(
    "GET",
    "https://www.sim.ai/api/v2/logs/string",
    headers={
  "X-API-Key": "YOUR_API_KEY"
},
)
response.raise_for_status()
result = response.json()
```

### Go

```go
package main

import (
  "io"
  "net/http"
  "os"
)

func check(err error) {
  if err != nil { panic(err) }
}

func must[T any](value T, err error) T {
  check(err)
  return value
}

func main() {

  request := must(http.NewRequest("GET", "https://www.sim.ai/api/v2/logs/string", nil))
  request.Header.Set("X-API-Key", "YOUR_API_KEY")
  response := must(http.DefaultClient.Do(request))
  defer response.Body.Close()
  if response.StatusCode >= 400 { panic(response.Status) }
  must(io.Copy(os.Stdout, response.Body))
}
```

### Java

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    var builder = HttpRequest.newBuilder(URI.create("https://www.sim.ai/api/v2/logs/string"));
    builder.header("X-API-Key", "YOUR_API_KEY");
    var request = builder.method("GET", HttpRequest.BodyPublishers.noBody()).build();
    var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofInputStream());
    try (var body = response.body()) {
      if (response.statusCode() >= 400) throw new IllegalStateException("HTTP " + response.statusCode());
      body.transferTo(System.out);
    }
  }
}
```

### C#

```csharp
using System;
using System.IO;
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.sim.ai/api/v2/logs/string");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_API_KEY");
using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
response.EnsureSuccessStatusCode();
await response.Content.CopyToAsync(Console.OpenStandardOutput());
```

## Parameters

```json

[
  {
    "name": "runId",
    "in": "path",
    "required": true,
    "description": "Unique workflow run identifier.",
    "schema": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._:-]+$",
      "description": "Unique workflow run identifier."
    }
  },
  {
    "name": "includeWorkflowState",
    "in": "query",
    "required": false,
    "description": "Include the saved workflow snapshot (default: true). Set false to omit block configuration from a log read. Other run fields are unchanged.",
    "schema": {
      "description": "Include the saved workflow snapshot (default: true). Set false to omit block configuration from a log read. Other run fields are unchanged.",
      "type": "boolean"
    }
  }
]

```

## Responses

### 200

```json

{
  "description": "The requested diagnostic log representation.",
  "headers": {
    "X-RateLimit-Limit": {
      "description": "Maximum requests allowed in the current window.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Rate limit",
        "description": "Maximum requests allowed in the current window."
      }
    },
    "X-RateLimit-Remaining": {
      "description": "Requests remaining in the current window.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Rate limit remaining",
        "description": "Requests remaining in the current window."
      }
    },
    "X-RateLimit-Reset": {
      "description": "ISO 8601 timestamp when the current rate-limit window resets.",
      "schema": {
        "type": "string",
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
        "title": "Rate limit reset",
        "description": "ISO 8601 timestamp when the current rate-limit window resets."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "runId": {
                "type": "string",
                "description": "Unique run identifier."
              },
              "workflowId": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Workflow identifier, or null when unavailable."
              },
              "deploymentVersionId": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Deployment version identifier, or null when unavailable."
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "running",
                  "paused",
                  "redacting",
                  "completed",
                  "failed",
                  "cancelled"
                ],
                "description": "Current execution status, reported as persisted. `redacting` is transient while run output is scrubbed. `paused` is reported only when a resume attempt did not complete; a run held at a human-in-the-loop pause point reads `pending` here, and `paused` on the workflow run resources. Use those when the pause state matters."
              },
              "level": {
                "type": "string",
                "description": "Log severity level."
              },
              "trigger": {
                "type": "string",
                "description": "Trigger that started the run."
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "ISO 8601 execution start timestamp."
              },
              "endedAt": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "ISO 8601 execution end timestamp, or null while the run is active."
              },
              "totalDurationMs": {
                "anyOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Total execution duration in milliseconds, or null while unavailable."
              },
              "files": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Identifier to address this file by on the download endpoint."
                        },
                        "name": {
                          "type": "string",
                          "description": "File name, including its extension."
                        },
                        "size": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991,
                          "description": "File size in bytes."
                        },
                        "type": {
                          "type": "string",
                          "description": "MIME type recorded for the file."
                        },
                        "downloadPath": {
                          "type": "string",
                          "description": "Path to fetch this file's bytes from, relative to the API host."
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "size",
                        "type",
                        "downloadPath"
                      ],
                      "additionalProperties": false,
                      "title": "Execution log file",
                      "description": "A file produced by the run this log records."
                    }
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Files the run produced, or null when none are recorded. Only the run's own output files appear; input attachments a caller supplied are addressed through the files API instead."
              },
              "executedByEmail": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "email",
                    "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Email of the identity the run executed as: the caller for an interactive or personal-API-key run, and the workspace billing account for a schedule, webhook, deployed chat, or public API call. Null when the run failed before an identity was resolved."
              },
              "workflow": {
                "type": "object",
                "properties": {
                  "id": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Workflow identifier, or null when unavailable."
                  },
                  "name": {
                    "type": "string",
                    "description": "Workflow name."
                  },
                  "description": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Workflow description, or null when unset."
                  },
                  "folderPath": {
                    "anyOf": [
                      {
                        "type": "string",
                        "title": "Folder path",
                        "description": "Canonical slash-prefixed folder path. `/` is the workspace root. Segments are percent-encoded, so a folder shown as \"New folder\" is `/New%20folder`: everything outside `A-Z a-z 0-9 - _ . ~` is escaped as uppercase hex, and only that exact encoding is accepted. A trailing slash, an empty segment, and a literal `.` or `..` segment are rejected. At most 64 segments and 4096 encoded bytes.",
                        "maxLength": 4096
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Canonical folder path of the workflow, in the same form `folderPaths` accepts as a filter: `/` for a workflow at the workspace root. Null only when the path cannot be resolved — the folder has been deleted, or the workflow itself no longer exists."
                  },
                  "ownerEmail": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "email",
                        "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Deprecated — use the run-level `executedByEmail` instead. Email of the workflow's current owner, or null when unavailable. This is a property of the workflow as it stands today, not of the run: it changes when workflow ownership is reassigned, and the owner is not the identity a background run executes as.",
                    "deprecated": true
                  },
                  "workspaceId": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Owning workspace identifier, or null when unavailable."
                  },
                  "createdAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "ISO 8601 workflow creation timestamp, or null when unavailable."
                  },
                  "updatedAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "ISO 8601 workflow update timestamp, or null when unavailable."
                  },
                  "deleted": {
                    "type": "boolean",
                    "description": "Whether the workflow has been deleted."
                  }
                },
                "required": [
                  "id",
                  "name",
                  "description",
                  "folderPath",
                  "ownerEmail",
                  "workspaceId",
                  "createdAt",
                  "updatedAt",
                  "deleted"
                ],
                "additionalProperties": false,
                "description": "Workflow snapshot associated with the execution."
              },
              "workflowState": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": {
                      "description": "One top-level snapshot section — `blocks`, `edges`, `loops`, `parallels`, or `variables` — passed through as stored."
                    }
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Workflow graph captured for the run, or null if unavailable or includeWorkflowState=false. Sensitive values are redacted to null; environment-variable references may be preserved."
              },
              "traceSpans": {
                "type": "array",
                "items": {
                  "title": "Log trace span",
                  "description": "One recursive operation span in a workflow execution trace.",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Trace-span identifier."
                    },
                    "name": {
                      "type": "string",
                      "description": "Trace-span name."
                    },
                    "type": {
                      "type": "string",
                      "description": "Trace-span category."
                    },
                    "duration": {
                      "type": "number",
                      "description": "Current trace-span duration in milliseconds."
                    },
                    "durationMs": {
                      "type": "number",
                      "description": "Compatibility field for span duration in milliseconds. Read `duration` for current trace spans."
                    },
                    "startTime": {
                      "type": "string",
                      "description": "ISO 8601 span start timestamp."
                    },
                    "endTime": {
                      "type": "string",
                      "description": "ISO 8601 span end timestamp."
                    },
                    "status": {
                      "type": "string",
                      "description": "Trace-span status."
                    },
                    "errorHandled": {
                      "type": "boolean",
                      "description": "Whether the recorded error was handled."
                    },
                    "errorType": {
                      "type": "string",
                      "description": "Recorded error type."
                    },
                    "errorMessage": {
                      "type": "string",
                      "description": "Recorded error message."
                    },
                    "blockId": {
                      "type": "string",
                      "description": "Workflow block associated with the span."
                    },
                    "input": {
                      "description": "Input captured for the traced operation."
                    },
                    "output": {
                      "description": "Output captured for the traced operation."
                    },
                    "tokens": {
                      "anyOf": [
                        {
                          "type": "number",
                          "description": "Total tokens attributed to the span."
                        },
                        {
                          "type": "object",
                          "properties": {
                            "total": {
                              "type": "number",
                              "description": "Total tokens."
                            },
                            "input": {
                              "type": "number",
                              "description": "Input tokens."
                            },
                            "output": {
                              "type": "number",
                              "description": "Output tokens."
                            }
                          },
                          "additionalProperties": false
                        }
                      ],
                      "description": "Token usage attributed to the span."
                    },
                    "cost": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "number",
                          "description": "Total span cost in USD."
                        },
                        "input": {
                          "type": "number",
                          "description": "Input-token cost in USD."
                        },
                        "output": {
                          "type": "number",
                          "description": "Output-token cost in USD."
                        },
                        "toolCost": {
                          "type": "number",
                          "description": "Tool cost in USD."
                        }
                      },
                      "additionalProperties": false,
                      "description": "Cost attributed to the span."
                    },
                    "relativeStartMs": {
                      "type": "number",
                      "description": "Offset from the root span in milliseconds."
                    },
                    "contentWithheld": {
                      "type": "boolean",
                      "const": true,
                      "description": "Present when the log projection withheld some or all of this span's content (input, output, thinking, error message, tool-call or provider-segment content) because it could not be proven safe to display. Status, timing, and usage remain. A withheld content field is omitted whole, never a key inside it: a content field absent from a span carrying this marker may exist on the run but was not returned, while a key missing inside a content field that is present is genuinely absent."
                    },
                    "toolCalls": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Tool-call identifier."
                          },
                          "name": {
                            "type": "string",
                            "description": "Invoked tool name."
                          },
                          "arguments": {
                            "description": "Arguments supplied to the tool call."
                          },
                          "result": {
                            "description": "Value returned by the tool call."
                          },
                          "error": {
                            "type": "string",
                            "description": "Tool-call error message."
                          },
                          "startTime": {
                            "type": "string",
                            "description": "ISO 8601 tool-call start timestamp."
                          },
                          "endTime": {
                            "type": "string",
                            "description": "ISO 8601 tool-call end timestamp."
                          },
                          "duration": {
                            "type": "number",
                            "description": "Tool-call duration in milliseconds."
                          }
                        },
                        "additionalProperties": {
                          "description": "Additional provider-specific tool-call metadata."
                        }
                      },
                      "description": "Tool calls recorded by the span."
                    },
                    "children": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/LogTraceSpan"
                      },
                      "description": "Nested child trace spans."
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "type"
                  ],
                  "additionalProperties": {
                    "description": "Additional provider-specific trace-span metadata."
                  }
                },
                "description": "Materialized block-level execution trace spans."
              },
              "finalOutput": {
                "anyOf": [
                  {
                    "description": "Materialized final workflow output value."
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Materialized final workflow output, or null when none was produced."
              },
              "cost": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "total": {
                        "type": "number",
                        "description": "Total execution cost in USD."
                      },
                      "items": {
                        "anyOf": [
                          {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "category": {
                                  "type": "string",
                                  "enum": [
                                    "fixed",
                                    "model",
                                    "tool"
                                  ],
                                  "description": "What the line is for: the run's base fee (`fixed`), one model's inference (`model`), or one metered tool or integration call (`tool`)."
                                },
                                "description": {
                                  "type": "string",
                                  "description": "Human-readable name of the billed item, such as the model or tool id."
                                },
                                "cost": {
                                  "type": "number",
                                  "description": "Amount billed for this line, in USD."
                                },
                                "inputTokens": {
                                  "description": "Input tokens attributed to this line. Absent for lines that do not bill tokens.",
                                  "type": "number"
                                },
                                "outputTokens": {
                                  "description": "Output tokens attributed to this line. Absent for lines that do not bill tokens.",
                                  "type": "number"
                                }
                              },
                              "required": [
                                "category",
                                "description",
                                "cost"
                              ],
                              "additionalProperties": false,
                              "description": "One billed line of a run, folded across every event that billed it."
                            }
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Billed lines reconciling to `total`, or null when no itemized ledger exists for the run."
                      }
                    },
                    "required": [
                      "total",
                      "items"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Cost charged for the run, or null when unavailable."
              },
              "workflowInput": {
                "anyOf": [
                  {
                    "description": "Caller-supplied trigger payload for the run."
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Input the run was triggered with, or null when the run recorded none. Credential-bearing and PII-masked values are redacted the same way `finalOutput` is."
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "ISO 8601 log creation timestamp."
              }
            },
            "required": [
              "runId",
              "workflowId",
              "deploymentVersionId",
              "status",
              "level",
              "trigger",
              "startedAt",
              "endedAt",
              "totalDurationMs",
              "files",
              "executedByEmail",
              "workflow",
              "workflowState",
              "traceSpans",
              "finalOutput",
              "cost",
              "workflowInput",
              "createdAt"
            ],
            "additionalProperties": false,
            "title": "Execution log detail",
            "description": "Response data."
          }
        },
        "required": [
          "data"
        ],
        "additionalProperties": false,
        "title": "Log detail response",
        "description": "The complete diagnostic representation of a workflow run.",
        "examples": [
          {
            "data": {
              "runId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
              "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
              "deploymentVersionId": "dep_2c4e6a8b0d1f",
              "status": "completed",
              "level": "info",
              "trigger": "api",
              "startedAt": "2026-01-15T10:30:00.000Z",
              "endedAt": "2026-01-15T10:30:01.250Z",
              "totalDurationMs": 1250,
              "files": [
                {
                  "id": "f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04",
                  "name": "summary.pdf",
                  "size": 18422,
                  "type": "application/pdf",
                  "downloadPath": "/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13/files/f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04"
                }
              ],
              "executedByEmail": "billing@example.com",
              "workflow": {
                "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
                "name": "Customer Support Agent",
                "description": "Routes incoming support tickets and drafts responses",
                "folderPath": "/",
                "ownerEmail": "jane@example.com",
                "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
                "createdAt": "2025-01-10T09:00:00.000Z",
                "updatedAt": "2025-06-18T16:45:00.000Z",
                "deleted": false
              },
              "workflowState": {
                "blocks": {},
                "edges": []
              },
              "traceSpans": [],
              "finalOutput": {
                "result": "Hello, world!"
              },
              "cost": {
                "total": 0.0072,
                "items": [
                  {
                    "category": "fixed",
                    "description": "Base execution charge",
                    "cost": 0.005
                  },
                  {
                    "category": "model",
                    "description": "gpt-5",
                    "cost": 0.0022,
                    "inputTokens": 1840,
                    "outputTokens": 260
                  }
                ]
              },
              "workflowInput": {
                "ticketId": "T-4821"
              },
              "createdAt": "2026-01-15T10:30:00.000Z"
            }
          }
        ]
      },
      "examples": {
        "example1": {
          "summary": "Response example 1",
          "value": {
            "data": {
              "runId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
              "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
              "deploymentVersionId": "dep_2c4e6a8b0d1f",
              "status": "completed",
              "level": "info",
              "trigger": "api",
              "startedAt": "2026-01-15T10:30:00.000Z",
              "endedAt": "2026-01-15T10:30:01.250Z",
              "totalDurationMs": 1250,
              "files": [
                {
                  "id": "f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04",
                  "name": "summary.pdf",
                  "size": 18422,
                  "type": "application/pdf",
                  "downloadPath": "/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13/files/f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04"
                }
              ],
              "executedByEmail": "billing@example.com",
              "workflow": {
                "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
                "name": "Customer Support Agent",
                "description": "Routes incoming support tickets and drafts responses",
                "folderPath": "/",
                "ownerEmail": "jane@example.com",
                "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
                "createdAt": "2025-01-10T09:00:00.000Z",
                "updatedAt": "2025-06-18T16:45:00.000Z",
                "deleted": false
              },
              "workflowState": {
                "blocks": {},
                "edges": []
              },
              "traceSpans": [],
              "finalOutput": {
                "result": "Hello, world!"
              },
              "cost": {
                "total": 0.0072,
                "items": [
                  {
                    "category": "fixed",
                    "description": "Base execution charge",
                    "cost": 0.005
                  },
                  {
                    "category": "model",
                    "description": "gpt-5",
                    "cost": 0.0022,
                    "inputTokens": 1840,
                    "outputTokens": 260
                  }
                ]
              },
              "workflowInput": {
                "ticketId": "T-4821"
              },
              "createdAt": "2026-01-15T10:30:00.000Z"
            }
          }
        }
      }
    }
  }
}

```

### 400

```json

{
  "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "BAD_REQUEST",
          "message": "Invalid request"
        }
      }
    }
  }
}

```

### 401

```json

{
  "description": "The API credential is missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "UNAUTHORIZED",
          "message": "Authentication required"
        }
      }
    }
  }
}

```

### 403

```json

{
  "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "FORBIDDEN",
          "message": "Insufficient workspace permissions",
          "details": {
            "code": "INSUFFICIENT_WORKSPACE_ROLE"
          }
        }
      }
    }
  }
}

```

### 404

```json

{
  "description": "The requested resource was not found.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "NOT_FOUND",
          "message": "Not found"
        }
      }
    }
  }
}

```

### 413

```json

{
  "description": "The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "PAYLOAD_TOO_LARGE",
          "message": "Request body is too large"
        }
      }
    }
  }
}

```

### 429

```json

{
  "description": "The caller exceeded the request rate limit.",
  "headers": {
    "Retry-After": {
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Retry after",
        "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "RATE_LIMITED",
          "message": "API rate limit exceeded",
          "details": {
            "retryAfter": "2026-01-01T00:00:30.000Z"
          }
        }
      }
    }
  }
}

```

### 500

```json

{
  "description": "An unexpected server error occurred.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "INTERNAL_ERROR",
          "message": "Internal server error"
        }
      }
    }
  }
}

```

### 503

```json

{
  "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
  "headers": {
    "Retry-After": {
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Retry after",
        "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "SERVICE_UNAVAILABLE",
          "message": "Service temporarily unavailable"
        }
      }
    }
  }
}

```

## Referenced schemas

The following definitions preserve recursive references and composition exactly.

```json

{
  "#/components/headers/X-RateLimit-Limit": {
    "description": "Maximum requests allowed in the current window.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Rate limit",
      "description": "Maximum requests allowed in the current window."
    }
  },
  "#/components/headers/X-RateLimit-Remaining": {
    "description": "Requests remaining in the current window.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Rate limit remaining",
      "description": "Requests remaining in the current window."
    }
  },
  "#/components/headers/X-RateLimit-Reset": {
    "description": "ISO 8601 timestamp when the current rate-limit window resets.",
    "schema": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "title": "Rate limit reset",
      "description": "ISO 8601 timestamp when the current rate-limit window resets."
    }
  },
  "#/components/schemas/V2LogDetailResponse": {
    "type": "object",
    "properties": {
      "data": {
        "description": "Response data.",
        "$ref": "#/components/schemas/V2LogDetail"
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false,
    "title": "Log detail response",
    "description": "The complete diagnostic representation of a workflow run.",
    "examples": [
      {
        "data": {
          "runId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
          "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
          "deploymentVersionId": "dep_2c4e6a8b0d1f",
          "status": "completed",
          "level": "info",
          "trigger": "api",
          "startedAt": "2026-01-15T10:30:00.000Z",
          "endedAt": "2026-01-15T10:30:01.250Z",
          "totalDurationMs": 1250,
          "files": [
            {
              "id": "f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04",
              "name": "summary.pdf",
              "size": 18422,
              "type": "application/pdf",
              "downloadPath": "/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13/files/f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04"
            }
          ],
          "executedByEmail": "billing@example.com",
          "workflow": {
            "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
            "name": "Customer Support Agent",
            "description": "Routes incoming support tickets and drafts responses",
            "folderPath": "/",
            "ownerEmail": "jane@example.com",
            "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
            "createdAt": "2025-01-10T09:00:00.000Z",
            "updatedAt": "2025-06-18T16:45:00.000Z",
            "deleted": false
          },
          "workflowState": {
            "blocks": {},
            "edges": []
          },
          "traceSpans": [],
          "finalOutput": {
            "result": "Hello, world!"
          },
          "cost": {
            "total": 0.0072,
            "items": [
              {
                "category": "fixed",
                "description": "Base execution charge",
                "cost": 0.005
              },
              {
                "category": "model",
                "description": "gpt-5",
                "cost": 0.0022,
                "inputTokens": 1840,
                "outputTokens": 260
              }
            ]
          },
          "workflowInput": {
            "ticketId": "T-4821"
          },
          "createdAt": "2026-01-15T10:30:00.000Z"
        }
      }
    ]
  },
  "#/components/schemas/V2LogDetail": {
    "type": "object",
    "properties": {
      "runId": {
        "type": "string",
        "description": "Unique run identifier."
      },
      "workflowId": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "Workflow identifier, or null when unavailable."
      },
      "deploymentVersionId": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "Deployment version identifier, or null when unavailable."
      },
      "status": {
        "type": "string",
        "enum": [
          "pending",
          "running",
          "paused",
          "redacting",
          "completed",
          "failed",
          "cancelled"
        ],
        "description": "Current execution status, reported as persisted. `redacting` is transient while run output is scrubbed. `paused` is reported only when a resume attempt did not complete; a run held at a human-in-the-loop pause point reads `pending` here, and `paused` on the workflow run resources. Use those when the pause state matters."
      },
      "level": {
        "type": "string",
        "description": "Log severity level."
      },
      "trigger": {
        "type": "string",
        "description": "Trigger that started the run."
      },
      "startedAt": {
        "type": "string",
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
        "description": "ISO 8601 execution start timestamp."
      },
      "endedAt": {
        "anyOf": [
          {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
          },
          {
            "type": "null"
          }
        ],
        "description": "ISO 8601 execution end timestamp, or null while the run is active."
      },
      "totalDurationMs": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "null"
          }
        ],
        "description": "Total execution duration in milliseconds, or null while unavailable."
      },
      "files": {
        "anyOf": [
          {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V2LogFile"
            }
          },
          {
            "type": "null"
          }
        ],
        "description": "Files the run produced, or null when none are recorded. Only the run's own output files appear; input attachments a caller supplied are addressed through the files API instead."
      },
      "executedByEmail": {
        "anyOf": [
          {
            "type": "string",
            "format": "email",
            "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
          },
          {
            "type": "null"
          }
        ],
        "description": "Email of the identity the run executed as: the caller for an interactive or personal-API-key run, and the workspace billing account for a schedule, webhook, deployed chat, or public API call. Null when the run failed before an identity was resolved."
      },
      "workflow": {
        "type": "object",
        "properties": {
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Workflow identifier, or null when unavailable."
          },
          "name": {
            "type": "string",
            "description": "Workflow name."
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Workflow description, or null when unset."
          },
          "folderPath": {
            "anyOf": [
              {
                "type": "string",
                "title": "Folder path",
                "description": "Canonical slash-prefixed folder path. `/` is the workspace root. Segments are percent-encoded, so a folder shown as \"New folder\" is `/New%20folder`: everything outside `A-Z a-z 0-9 - _ . ~` is escaped as uppercase hex, and only that exact encoding is accepted. A trailing slash, an empty segment, and a literal `.` or `..` segment are rejected. At most 64 segments and 4096 encoded bytes.",
                "maxLength": 4096
              },
              {
                "type": "null"
              }
            ],
            "description": "Canonical folder path of the workflow, in the same form `folderPaths` accepts as a filter: `/` for a workflow at the workspace root. Null only when the path cannot be resolved — the folder has been deleted, or the workflow itself no longer exists."
          },
          "ownerEmail": {
            "anyOf": [
              {
                "type": "string",
                "format": "email",
                "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
              },
              {
                "type": "null"
              }
            ],
            "description": "Deprecated — use the run-level `executedByEmail` instead. Email of the workflow's current owner, or null when unavailable. This is a property of the workflow as it stands today, not of the run: it changes when workflow ownership is reassigned, and the owner is not the identity a background run executes as.",
            "deprecated": true
          },
          "workspaceId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Owning workspace identifier, or null when unavailable."
          },
          "createdAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 workflow creation timestamp, or null when unavailable."
          },
          "updatedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 workflow update timestamp, or null when unavailable."
          },
          "deleted": {
            "type": "boolean",
            "description": "Whether the workflow has been deleted."
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "folderPath",
          "ownerEmail",
          "workspaceId",
          "createdAt",
          "updatedAt",
          "deleted"
        ],
        "additionalProperties": false,
        "description": "Workflow snapshot associated with the execution."
      },
      "workflowState": {
        "anyOf": [
          {
            "type": "object",
            "properties": {},
            "additionalProperties": {
              "description": "One top-level snapshot section — `blocks`, `edges`, `loops`, `parallels`, or `variables` — passed through as stored."
            }
          },
          {
            "type": "null"
          }
        ],
        "description": "Workflow graph captured for the run, or null if unavailable or includeWorkflowState=false. Sensitive values are redacted to null; environment-variable references may be preserved."
      },
      "traceSpans": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/LogTraceSpan"
        },
        "description": "Materialized block-level execution trace spans."
      },
      "finalOutput": {
        "anyOf": [
          {
            "description": "Materialized final workflow output value."
          },
          {
            "type": "null"
          }
        ],
        "description": "Materialized final workflow output, or null when none was produced."
      },
      "cost": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "total": {
                "type": "number",
                "description": "Total execution cost in USD."
              },
              "items": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "category": {
                          "type": "string",
                          "enum": [
                            "fixed",
                            "model",
                            "tool"
                          ],
                          "description": "What the line is for: the run's base fee (`fixed`), one model's inference (`model`), or one metered tool or integration call (`tool`)."
                        },
                        "description": {
                          "type": "string",
                          "description": "Human-readable name of the billed item, such as the model or tool id."
                        },
                        "cost": {
                          "type": "number",
                          "description": "Amount billed for this line, in USD."
                        },
                        "inputTokens": {
                          "description": "Input tokens attributed to this line. Absent for lines that do not bill tokens.",
                          "type": "number"
                        },
                        "outputTokens": {
                          "description": "Output tokens attributed to this line. Absent for lines that do not bill tokens.",
                          "type": "number"
                        }
                      },
                      "required": [
                        "category",
                        "description",
                        "cost"
                      ],
                      "additionalProperties": false,
                      "description": "One billed line of a run, folded across every event that billed it."
                    }
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Billed lines reconciling to `total`, or null when no itemized ledger exists for the run."
              }
            },
            "required": [
              "total",
              "items"
            ],
            "additionalProperties": false
          },
          {
            "type": "null"
          }
        ],
        "description": "Cost charged for the run, or null when unavailable."
      },
      "workflowInput": {
        "anyOf": [
          {
            "description": "Caller-supplied trigger payload for the run."
          },
          {
            "type": "null"
          }
        ],
        "description": "Input the run was triggered with, or null when the run recorded none. Credential-bearing and PII-masked values are redacted the same way `finalOutput` is."
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
        "description": "ISO 8601 log creation timestamp."
      }
    },
    "required": [
      "runId",
      "workflowId",
      "deploymentVersionId",
      "status",
      "level",
      "trigger",
      "startedAt",
      "endedAt",
      "totalDurationMs",
      "files",
      "executedByEmail",
      "workflow",
      "workflowState",
      "traceSpans",
      "finalOutput",
      "cost",
      "workflowInput",
      "createdAt"
    ],
    "additionalProperties": false,
    "title": "Execution log detail",
    "description": "Response data."
  },
  "#/components/schemas/V2LogFile": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Identifier to address this file by on the download endpoint."
      },
      "name": {
        "type": "string",
        "description": "File name, including its extension."
      },
      "size": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "File size in bytes."
      },
      "type": {
        "type": "string",
        "description": "MIME type recorded for the file."
      },
      "downloadPath": {
        "type": "string",
        "description": "Path to fetch this file's bytes from, relative to the API host."
      }
    },
    "required": [
      "id",
      "name",
      "size",
      "type",
      "downloadPath"
    ],
    "additionalProperties": false,
    "title": "Execution log file",
    "description": "A file produced by the run this log records."
  },
  "#/components/schemas/LogTraceSpan": {
    "title": "Log trace span",
    "description": "One recursive operation span in a workflow execution trace.",
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Trace-span identifier."
      },
      "name": {
        "type": "string",
        "description": "Trace-span name."
      },
      "type": {
        "type": "string",
        "description": "Trace-span category."
      },
      "duration": {
        "type": "number",
        "description": "Current trace-span duration in milliseconds."
      },
      "durationMs": {
        "type": "number",
        "description": "Compatibility field for span duration in milliseconds. Read `duration` for current trace spans."
      },
      "startTime": {
        "type": "string",
        "description": "ISO 8601 span start timestamp."
      },
      "endTime": {
        "type": "string",
        "description": "ISO 8601 span end timestamp."
      },
      "status": {
        "type": "string",
        "description": "Trace-span status."
      },
      "errorHandled": {
        "type": "boolean",
        "description": "Whether the recorded error was handled."
      },
      "errorType": {
        "type": "string",
        "description": "Recorded error type."
      },
      "errorMessage": {
        "type": "string",
        "description": "Recorded error message."
      },
      "blockId": {
        "type": "string",
        "description": "Workflow block associated with the span."
      },
      "input": {
        "description": "Input captured for the traced operation."
      },
      "output": {
        "description": "Output captured for the traced operation."
      },
      "tokens": {
        "anyOf": [
          {
            "type": "number",
            "description": "Total tokens attributed to the span."
          },
          {
            "type": "object",
            "properties": {
              "total": {
                "type": "number",
                "description": "Total tokens."
              },
              "input": {
                "type": "number",
                "description": "Input tokens."
              },
              "output": {
                "type": "number",
                "description": "Output tokens."
              }
            },
            "additionalProperties": false
          }
        ],
        "description": "Token usage attributed to the span."
      },
      "cost": {
        "type": "object",
        "properties": {
          "total": {
            "type": "number",
            "description": "Total span cost in USD."
          },
          "input": {
            "type": "number",
            "description": "Input-token cost in USD."
          },
          "output": {
            "type": "number",
            "description": "Output-token cost in USD."
          },
          "toolCost": {
            "type": "number",
            "description": "Tool cost in USD."
          }
        },
        "additionalProperties": false,
        "description": "Cost attributed to the span."
      },
      "relativeStartMs": {
        "type": "number",
        "description": "Offset from the root span in milliseconds."
      },
      "contentWithheld": {
        "type": "boolean",
        "const": true,
        "description": "Present when the log projection withheld some or all of this span's content (input, output, thinking, error message, tool-call or provider-segment content) because it could not be proven safe to display. Status, timing, and usage remain. A withheld content field is omitted whole, never a key inside it: a content field absent from a span carrying this marker may exist on the run but was not returned, while a key missing inside a content field that is present is genuinely absent."
      },
      "toolCalls": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "Tool-call identifier."
            },
            "name": {
              "type": "string",
              "description": "Invoked tool name."
            },
            "arguments": {
              "description": "Arguments supplied to the tool call."
            },
            "result": {
              "description": "Value returned by the tool call."
            },
            "error": {
              "type": "string",
              "description": "Tool-call error message."
            },
            "startTime": {
              "type": "string",
              "description": "ISO 8601 tool-call start timestamp."
            },
            "endTime": {
              "type": "string",
              "description": "ISO 8601 tool-call end timestamp."
            },
            "duration": {
              "type": "number",
              "description": "Tool-call duration in milliseconds."
            }
          },
          "additionalProperties": {
            "description": "Additional provider-specific tool-call metadata."
          }
        },
        "description": "Tool calls recorded by the span."
      },
      "children": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/LogTraceSpan"
        },
        "description": "Nested child trace spans."
      }
    },
    "required": [
      "id",
      "name",
      "type"
    ],
    "additionalProperties": {
      "description": "Additional provider-specific trace-span metadata."
    }
  },
  "#/components/responses/BadRequest": {
    "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "BAD_REQUEST",
            "message": "Invalid request"
          }
        }
      }
    }
  },
  "#/components/schemas/V2Error": {
    "type": "object",
    "properties": {
      "error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code."
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation of the error."
          },
          "details": {
            "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/V2ActionableForbiddenDetails"
              },
              {
                "description": "Other structured context defined by the specific error."
              }
            ]
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false,
        "description": "Canonical error details."
      }
    },
    "required": [
      "error"
    ],
    "additionalProperties": false,
    "title": "v2 error response",
    "description": "Canonical error envelope returned by the public v2 API.",
    "examples": [
      {
        "error": {
          "code": "BAD_REQUEST",
          "message": "The request is invalid."
        }
      }
    ]
  },
  "#/components/schemas/V2ActionableForbiddenDetails": {
    "type": "object",
    "properties": {
      "code": {
        "$ref": "#/components/schemas/V2ForbiddenDetailCode"
      }
    },
    "required": [
      "code"
    ],
    "additionalProperties": {
      "description": "Additional context for this refusal."
    },
    "title": "Actionable forbidden details",
    "description": "Machine-readable cause and optional context for an actionable `403` response."
  },
  "#/components/schemas/V2ForbiddenDetailCode": {
    "type": "string",
    "enum": [
      "INSUFFICIENT_WORKSPACE_ROLE",
      "PERSONAL_API_KEYS_DISABLED",
      "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
      "PRINCIPAL_KIND_NOT_PERMITTED",
      "ORGANIZATION_MEMBERSHIP_REQUIRED",
      "ORGANIZATION_ADMIN_REQUIRED",
      "ENTERPRISE_PLAN_REQUIRED",
      "SSO_DISABLED",
      "SSO_DOMAIN_NOT_VERIFIED",
      "SSO_PROVIDER_LIMIT_REACHED",
      "ORGANIZATION_PLAN_REQUIRED",
      "AUDIT_LOGS_DISABLED",
      "ACCESS_REQUESTS_DISABLED",
      "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
      "SKILL_EDITOR_ACCESS_REQUIRED",
      "SECRET_ADMIN_ACCESS_REQUIRED",
      "WORKSPACE_RESOURCE_LIMIT_REACHED",
      "PUBLIC_SHARING_NOT_ALLOWED",
      "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
      "MCP_SERVER_URL_NOT_ALLOWED",
      "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
      "CHAT_AUTH_MODE_NOT_PERMITTED",
      "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
      "PERMISSION_GROUP_CAPABILITY_BLOCKED",
      "INTEGRATION_NOT_ALLOWED",
      "INSUFFICIENT_SCOPE",
      "SCIM_MANAGED_MEMBERSHIP"
    ],
    "title": "Forbidden detail code",
    "description": "Stable cause code for an actionable `403` response."
  },
  "#/components/responses/Unauthorized": {
    "description": "The API credential is missing or invalid.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "UNAUTHORIZED",
            "message": "Authentication required"
          }
        }
      }
    }
  },
  "#/components/responses/Forbidden": {
    "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "FORBIDDEN",
            "message": "Insufficient workspace permissions",
            "details": {
              "code": "INSUFFICIENT_WORKSPACE_ROLE"
            }
          }
        }
      }
    }
  },
  "#/components/responses/NotFound": {
    "description": "The requested resource was not found.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "NOT_FOUND",
            "message": "Not found"
          }
        }
      }
    }
  },
  "#/components/responses/PayloadTooLarge": {
    "description": "The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "PAYLOAD_TOO_LARGE",
            "message": "Request body is too large"
          }
        }
      }
    }
  },
  "#/components/responses/RateLimited": {
    "description": "The caller exceeded the request rate limit.",
    "headers": {
      "Retry-After": {
        "$ref": "#/components/headers/Retry-After"
      }
    },
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "RATE_LIMITED",
            "message": "API rate limit exceeded",
            "details": {
              "retryAfter": "2026-01-01T00:00:30.000Z"
            }
          }
        }
      }
    }
  },
  "#/components/headers/Retry-After": {
    "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Retry after",
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
    }
  },
  "#/components/responses/InternalError": {
    "description": "An unexpected server error occurred.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "INTERNAL_ERROR",
            "message": "Internal server error"
          }
        }
      }
    }
  },
  "#/components/responses/ServiceUnavailable": {
    "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
    "headers": {
      "Retry-After": {
        "$ref": "#/components/headers/Retry-After"
      }
    },
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "SERVICE_UNAVAILABLE",
            "message": "Service temporarily unavailable"
          }
        }
      }
    }
  }
}

```

[Download OpenAPI specification](/openapi.json)

Source: `openapi-v2-logs.json`, operation `getLog`.