# 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"]}}}}
```