Topolo Docs Topolo Platform
Open workspace

Get Flow statistics

Read workspace flow totals and run results from the preceding 24 hours.

Outcome

Read workspace flow totals and run results from the preceding 24 hours.

Before you start

  • Verify authenticated identity, environment and the approved organization context before preparing an action.
  • The published application permission is workspace:read. Discover and bind the exact granted Flow workspace. Supplied ids do not grant access.
  • Session callers need read workspace access. Auth-introspected API keys must bind that workspace and satisfy workspace:read. The application permission and workspace boundary are separate checks.

Discover the target

topolo whoami --json
topolo actions get app_topolo_flow.stats.get --detail --json
topolo resources topolo-flow --json
topolo workspaces list topolo-flow --json
  • Set FLOW_WORKSPACE_ID to the exact id returned by granted workspace discovery.

Request

GET /api/stats

Inspect and test this action. Save the exact input object as payload.json; resource context is supplied separately.

Input fields

Use an empty input object. Identity and resource context are separate from action input.

View the full input schema through the action reference or CLI/MCP discovery.

Effects

  • Reads total/active flows, runsToday/failedToday and eight most recent runs; failedToday includes error and partial runs.

Interpret the response

This response has no new target identifier. Resolve the exact target separately through the documented resource reads.

Compare stats with flows.list and runs.list; these counts do not prove live transport acceptance.

View the complete success schema. Success examples below preserve the actual exported Worker responses; errors have their original refusal shapes. CLI/MCP add their transport envelope, and --detail requests the full CLI response.

Worked examples

Captured from the actual exported Flow Worker with both local SQLite D1 stores and all committed migrations, synthetic Auth identity/grants and simulated Nexus, archive and Workflow-acceptance transports. Fixture credentials and identifiers authorize no live operation. No live provider invocation, credential storage, notification delivery, metering acceptance, durable Workflow execution, deployment, backup erasure or production completion is established by these captures. Refused examples explain boundaries and must not be executed as successful workflows.

Refused request · HTTP 401

Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof. Scenario: anonymous action.

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_flow.stats.get --data @payload.json --json
topolo actions plan app_topolo_flow.stats.get --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 401:

{
  "error": "Authentication token required"
}

HTTP 401. The handler refused this request. Resolve the exact cause before retrying; invalid input can be refused by CLI validation before reaching the handler.

Successful request

Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof. Scenario: stats.get.

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_flow.stats.get --data @payload.json --json
topolo actions plan app_topolo_flow.stats.get --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_flow.stats.get --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --detail --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_flow.stats.get",
    "input": {},
    "resourceType": "workspace",
    "resourceId": "<id returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "stats": {
    "total": 0,
    "active": 0,
    "runsToday": 0,
    "failedToday": 0
  },
  "recentRuns": []
}

HTTP 200. Compare stats with flows.list and runs.list; these counts do not prove live transport acceptance.

Another supported response

Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Nexus/archive transport. No live credentials, provider calls, delivery, deployment or durable Workflow execution proof. Scenario: stats.get.

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_flow.stats.get --data @payload.json --json
topolo actions plan app_topolo_flow.stats.get --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_flow.stats.get --resource-type workspace --resource-id "$FLOW_WORKSPACE_ID" --data @payload.json --detail --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_flow.stats.get",
    "input": {},
    "resourceType": "workspace",
    "resourceId": "<id returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "stats": {
    "total": 1,
    "active": 1,
    "runsToday": 1,
    "failedToday": 0
  },
  "recentRuns": [
    {
      "id": "run_ad5fdc8e1e0143789d89",
      "flowId": "flow_d16b892d0e89474a8f24",
      "orgId": "org_flow_fixture",
      "workspaceId": "ws_flow_fixture",
      "status": "success",
      "trigger": "manual",
      "triggerPayload": {
        "message": "Synthetic fixture"
      },
      "triggeredBy": "usr_flow_fixture",
      "startedAt": 1791218519897,
      "finishedAt": 1791218519930,
      "durationMs": 33,
      "error": null,
      "stepCount": 2
    }
  ]
}

HTTP 200. Compare stats with flows.list and runs.list; these counts do not prove live transport acceptance.

Verify the result

  • Compare stats with flows.list and runs.list; these counts do not prove live transport acceptance.

Errors and recovery

  • Authentication token required (HTTP 401): Authenticate normally in the approved environment and organization, verify identity, then rediscover the action and its granted resource before retrying.
  • organization_required (HTTP 403): Authenticate into the specifically approved organization. Do not guess a different organization or bypass the refusal.
  • action_permission_required (HTTP 403): The credential lacks the exact published application permission. Stop and obtain authorized access; changing target ids cannot grant it.
  • workspace_required (HTTP 400): Discover an explicitly granted Flow workspace and bind its exact resource id.

Preserve the exact status, response, request id and resource context. Runtime input validation, authentication and platform resource resolution can refuse a request before the handler. Dynamic dependency messages are not stable provider error codes.

Recovery boundary

Repeat this read in the same workspace; investigate runs.get for actual failure details.

  • List Flow runs: Read the newest retained run records for the selected workspace.
  • Get a Flow run: Read one retained execution record and its ordered step evidence.

Evidence

Captured from the actual exported Flow Worker with both local SQLite D1 stores and all committed migrations, synthetic Auth identity/grants and simulated Nexus, archive and Workflow-acceptance transports. Fixture credentials and identifiers authorize no live operation. No live provider invocation, credential storage, notification delivery, metering acceptance, durable Workflow execution, deployment, backup erasure or production completion is established by these captures. Original scenario labels and response digests are retained in the source fixtures.