# Flow Run Logs

## List Flow Runs

> Retrieves a paginated list of flow runs. Can be filtered by \`user\_id\`, \`flow\_id\`, \`flow\_version\_id\`, \`virtual\_environment\_id\`, \`trigger\`, \`status\`, date range, and other criteria.

```json
{"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Flow Run Logs"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: `<api-key>`"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}},"schemas":{"FlowRunsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FlowRuns"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"},"links":{"$ref":"#/components/schemas/PaginationLinks"}}},"FlowRuns":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier"},"name":{"type":"string"},"payload.id":{"type":"string"},"steps.name":{"type":"string"},"status":{"type":"string","enum":["Draft","Inactive","Deployed"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"flow_id":{"type":"object"},"flow_version_id":{"type":"object"},"virtual_environment_version":{"type":"object"},"user_id":{"type":"integer"},"trigger":{"type":"string","enum":["API","Manual","Router","Webhook","Schedule","Shape","Retry","Event","Callback"]},"summary":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time"},"duration":{"type":"object"},"retry_flow_run_id":{"type":"object"},"retried_flow_run":{"type":"array","items":{"type":"object"}},"has_warnings":{"type":"array","items":{"type":"object"}},"flow_run_logs":{"type":"array","items":{"type":"object"}},"flow":{"type":"array","items":{"type":"object"}},"flow_version":{"type":"array","items":{"type":"object"}},"metrics":{"type":"array","items":{"type":"object"}},"cpu_time":{"type":"string"},"payload_size":{"type":"string"},"operations_sent":{"type":"string"},"operations_received":{"type":"string"},"score":{"type":"string"},"starting_payload_count":{"type":"integer"},"starting_payload_size":{"type":"string"},"flow_steps_with_errors":{"type":"string"}}},"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer"},"from":{"type":"integer","nullable":true},"last_page":{"type":"integer"},"path":{"type":"string"},"per_page":{"type":"integer"},"to":{"type":"integer","nullable":true},"total":{"type":"integer"}}},"PaginationLinks":{"type":"object","properties":{"first":{"type":"string","format":"uri"},"last":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri","nullable":true},"next":{"type":"string","format":"uri","nullable":true}}}}},"paths":{"/api/v1/flow-runs":{"get":{"summary":"List Flow Runs","description":"Retrieves a paginated list of flow runs. Can be filtered by `user_id`, `flow_id`, `flow_version_id`, `virtual_environment_id`, `trigger`, `status`, date range, and other criteria.","parameters":[{"name":"filter[user_id]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by user_id."},{"name":"filter[flow_id]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by flow_id."},{"name":"filter[flow_version_id]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by flow_version_id."},{"name":"filter[virtual_environment_id]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by virtual_environment_id."},{"name":"filter[trigger]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by trigger."},{"name":"filter[status]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by status."},{"name":"filter[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by search."},{"name":"filter[started_before]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results to flow runs that started before the specified time. Accepts a Unix timestamp in milliseconds, e.g. `2026-03-01 19:00` converts to `1772391627000` so `1772391627000` is the parameter value."},{"name":"filter[started_after]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results to flow runs that started after the specified time. Accepts a Unix timestamp in milliseconds."},{"name":"filter[started_on]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results to flow runs that started on the specified date. Accepts a Unix timestamp in milliseconds."},{"name":"filter[retried]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by retried."},{"name":"filter[has_warnings]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by has_warnings."},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of relationships to include. Available: flowVersion, flowVersion.steps, flow, flowRunLogs, errorWarningLogs, flowRunLogs.flowStep, trackedData, metrics, cpuTime, payloadSize, operationsSent, operationsReceived, retriedFlowRun, virtualEnvironmentVersion, virtualEnvironmentVersion.virtualEnvironment"},{"name":"sort","in":"query","required":false,"schema":{"type":"string"},"description":"Sort field. Prefix with - for descending. Available: started_at"},{"name":"fields[trackedData]","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of trackedData fields to return. Available: id"},{"name":"fields[flow]","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of flow fields to return. Available: id, name"},{"name":"fields[flowVersion]","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of flowVersion fields to return. Available: steps.name"},{"name":"fields[retriedFlowRun]","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of retriedFlowRun fields to return. Available: id, status"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Number of results per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowRunsListResponse"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"}},"tags":["Flow Run Logs"]}}}}
```

## Get Flow Run

> Retrieves the details of a specific flow run.

```json
{"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Flow Run Logs"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: `<api-key>`"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}},"schemas":{"FlowRunsResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FlowRuns"}}},"FlowRuns":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier"},"name":{"type":"string"},"payload.id":{"type":"string"},"steps.name":{"type":"string"},"status":{"type":"string","enum":["Draft","Inactive","Deployed"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"flow_id":{"type":"object"},"flow_version_id":{"type":"object"},"virtual_environment_version":{"type":"object"},"user_id":{"type":"integer"},"trigger":{"type":"string","enum":["API","Manual","Router","Webhook","Schedule","Shape","Retry","Event","Callback"]},"summary":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time"},"duration":{"type":"object"},"retry_flow_run_id":{"type":"object"},"retried_flow_run":{"type":"array","items":{"type":"object"}},"has_warnings":{"type":"array","items":{"type":"object"}},"flow_run_logs":{"type":"array","items":{"type":"object"}},"flow":{"type":"array","items":{"type":"object"}},"flow_version":{"type":"array","items":{"type":"object"}},"metrics":{"type":"array","items":{"type":"object"}},"cpu_time":{"type":"string"},"payload_size":{"type":"string"},"operations_sent":{"type":"string"},"operations_received":{"type":"string"},"score":{"type":"string"},"starting_payload_count":{"type":"integer"},"starting_payload_size":{"type":"string"},"flow_steps_with_errors":{"type":"string"}}}}},"paths":{"/api/v1/flow-runs/{flow_run}":{"get":{"summary":"Get Flow Run","description":"Retrieves the details of a specific flow run.","parameters":[{"name":"flow_run","in":"path","required":true,"schema":{"type":"string"},"description":"The flow run identifier."},{"name":"filter[user_id]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by user_id."},{"name":"filter[flow_id]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by flow_id."},{"name":"filter[flow_version_id]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by flow_version_id."},{"name":"filter[virtual_environment_id]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by virtual_environment_id."},{"name":"filter[trigger]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by trigger."},{"name":"filter[status]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by status."},{"name":"filter[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by search."},{"name":"filter[started_before]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results to flow runs that started before the specified time. Accepts a Unix timestamp in milliseconds, e.g. `2026-03-01 19:00` converts to `1772391627000` so `1772391627000` is the parameter value."},{"name":"filter[started_after]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results to flow runs that started after the specified time. Accepts a Unix timestamp in milliseconds."},{"name":"filter[started_on]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results to flow runs that started on the specified date. Accepts a Unix timestamp in milliseconds."},{"name":"filter[retried]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by retried."},{"name":"filter[has_warnings]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by has_warnings."},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of relationships to include. Available: flowVersion, flowVersion.steps, flow, flowRunLogs, errorWarningLogs, flowRunLogs.flowStep, trackedData, metrics, cpuTime, payloadSize, operationsSent, operationsReceived, retriedFlowRun, virtualEnvironmentVersion, virtualEnvironmentVersion.virtualEnvironment"},{"name":"sort","in":"query","required":false,"schema":{"type":"string"},"description":"Sort field. Prefix with - for descending. Available: started_at"},{"name":"fields[trackedData]","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of trackedData fields to return. Available: id"},{"name":"fields[flow]","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of flow fields to return. Available: id, name"},{"name":"fields[flowVersion]","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of flowVersion fields to return. Available: steps.name"},{"name":"fields[retriedFlowRun]","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of retriedFlowRun fields to return. Available: id, status"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Number of results per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowRunsResponse"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"}},"tags":["Flow Run Logs"]}}}}
```

## Download Run Logs

> Queues a download of the detailed logs for a specific flow run. The downloaded file is added to the File Downloads section in General Settings.

```json
{"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Flow Run Logs"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: `<api-key>`"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}}},"paths":{"/api/v1/flow-runs/{flow_run}/download":{"get":{"summary":"Download Run Logs","description":"Queues a download of the detailed logs for a specific flow run. The downloaded file is added to the File Downloads section in General Settings.","parameters":[{"name":"flow_run","in":"path","required":true,"schema":{"type":"string"},"description":"The flow run identifier."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"}},"tags":["Flow Run Logs"]}}}}
```

## List Run Logs

> Retrieves a paginated list of logs for a specific flow run. Can be filtered by \`flow\_step\_id\`.

```json
{"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Flow Run Logs"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: `<api-key>`"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}},"schemas":{"FlowRunLogsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FlowRunLog"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"},"links":{"$ref":"#/components/schemas/PaginationLinks"}}},"FlowRunLog":{"type":"object","properties":{"id":{"type":"integer"},"flow_run_id":{"type":"integer"},"flow_step_id":{"type":"integer"},"log_level":{"type":"string"},"log_message":{"type":"string"},"message":{"type":"array","items":{"type":"object"}},"meta":{"type":"object"},"page_number":{"type":"string"},"attempts":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"flow_run":{"type":"object"},"flow_step":{"type":"object"},"flow_step_payload_count":{"type":"integer"},"flow_run_log_metadata":{"type":"object"},"payload_ids":{"type":"string"}}},"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer"},"from":{"type":"integer","nullable":true},"last_page":{"type":"integer"},"path":{"type":"string"},"per_page":{"type":"integer"},"to":{"type":"integer","nullable":true},"total":{"type":"integer"}}},"PaginationLinks":{"type":"object","properties":{"first":{"type":"string","format":"uri"},"last":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri","nullable":true},"next":{"type":"string","format":"uri","nullable":true}}}}},"paths":{"/api/v1/flow-runs/{flow_run}/flow-run-logs":{"get":{"summary":"List Run Logs","description":"Retrieves a paginated list of logs for a specific flow run. Can be filtered by `flow_step_id`.","parameters":[{"name":"flow_run","in":"path","required":true,"schema":{"type":"string"},"description":"The flow run identifier."},{"name":"filter[flow_step_id]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by flow_step_id."},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of relationships to include. Available: flowRun, flowStep, flowRunLogMetadata, flowRunLogPayloads, flowStep.payloads"},{"name":"fields[flowStep]","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of flowStep fields to return. Available: id, name, payload.id"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Number of results per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowRunLogsListResponse"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"}},"tags":["Flow Run Logs"]}}}}
```

## Get Run Log

> Retrieves the details of a specific flow run log.

```json
{"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Flow Run Logs"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: `<api-key>`"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}},"schemas":{"FlowRunLogResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FlowRunLog"}}},"FlowRunLog":{"type":"object","properties":{"id":{"type":"integer"},"flow_run_id":{"type":"integer"},"flow_step_id":{"type":"integer"},"log_level":{"type":"string"},"log_message":{"type":"string"},"message":{"type":"array","items":{"type":"object"}},"meta":{"type":"object"},"page_number":{"type":"string"},"attempts":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"flow_run":{"type":"object"},"flow_step":{"type":"object"},"flow_step_payload_count":{"type":"integer"},"flow_run_log_metadata":{"type":"object"},"payload_ids":{"type":"string"}}}}},"paths":{"/api/v1/flow-runs/{flow_run}/flow-run-logs/{flow_run_log}":{"get":{"summary":"Get Run Log","description":"Retrieves the details of a specific flow run log.","parameters":[{"name":"flow_run","in":"path","required":true,"schema":{"type":"string"},"description":"The flow run identifier."},{"name":"flow_run_log","in":"path","required":true,"schema":{"type":"string"},"description":"The flow run log identifier."},{"name":"filter[flow_step_id]","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results by flow_step_id."},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of relationships to include. Available: flowRun, flowStep, flowRunLogMetadata, flowRunLogPayloads, flowStep.payloads"},{"name":"fields[flowStep]","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of flowStep fields to return. Available: id, name, payload.id"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Number of results per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowRunLogResponse"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"}},"tags":["Flow Run Logs"]}}}}
```

## Retry Flow Run

> Retries a specific flow run.

```json
{"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Flow Run Logs"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: `<api-key>`"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/api/v1/flow-runs/{flow_run}/retry":{"post":{"summary":"Retry Flow Run","description":"Retries a specific flow run.","parameters":[{"name":"flow_run","in":"path","required":true,"schema":{"type":"string"},"description":"The flow run identifier."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Flow Run Logs"]}}}}
```

## Stop Flow Run

> Stops a specific flow run that is currently in progress.

```json
{"openapi":"3.0.0","info":{"title":"Patchworks Core API","version":"1.0.0"},"tags":[{"name":"Flow Run Logs"}],"servers":[{"url":"https://core.wearepatchworks.com"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key passed in the Authorization header. Format: `<api-key>`"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2 Bearer token obtained from POST /fabric/api/login"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/api/v1/flow-runs/{flow_run}/stop":{"post":{"summary":"Stop Flow Run","description":"Stops a specific flow run that is currently in progress.","parameters":[{"name":"flow_run","in":"path","required":true,"schema":{"type":"string"},"description":"The flow run identifier."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Unauthorized"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Flow Run Logs"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.wearepatchworks.com/product-documentation/api-reference/flow-logs-and-queue/flow-run-logs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.