Get Sign workspace metrics

Read bounded counts of retained envelopes, open sent/viewed envelopes and completed envelopes in the granted workspace. This widget does not report token-expiry proximity or a time-period count.

Outcome

Read bounded counts of retained envelopes, open sent/viewed envelopes and completed envelopes in the granted workspace. This widget does not report token-expiry proximity or a time-period count.

Before you start

Verify the environment, authenticated identity and specifically approved organization context.
The published application permission is workspace:read. Resolve and bind the exact canonical Sign workspace. A supplied id or organization membership alone grants no workspace access.
Session callers require read workspace access. API-key resource binding is verified by Auth; never treat a caller-supplied header as an independent grant.

Discover the target

topolo whoami --json
topolo actions get app_topolo_sign.widget.get --detail --json
topolo resources topolo-sign --json
topolo workspaces list topolo-sign --json

Set SIGN_WORKSPACE_ID to the exact granted workspace returned by discovery.

Request

GET /api/widget

Inspect and test this action. Save the reviewed input as payload.json. Supply resource context separately.

Input fields

Use an empty input object; credential and resource context are separate.

Read the complete input schema.

Effects

Read bounded counts of retained envelopes, open sent/viewed envelopes and completed envelopes in the granted workspace. This widget does not report token-expiry proximity or a time-period count.

Interpret the response

Read $.workspace.id for the returned workspace_widget identifier. An empty collection does not discover a target.

Inspect widgets[].resource.resourceId and workspace.id against the granted workspace. Inspect metric keys envelopes, pending and completed; all counts refer to retained workspace records.

Inspect the success schema. CLI/MCP add their transport envelope; --detail requests the full CLI result. HTTP 204 contains no JSON payload.

Worked examples

Captured from the exported Sign Worker with the existing SQLite-backed D1 harness applying all core, envelope and audit migrations to one local database, in-memory R2 and synthetic Auth/workspace/archive/Notify transports. These examples prove local validation, persistence and artifact production. They do not prove separate deployed D1 topology, real recipient consent, provider delivery or a live signed agreement. All identities, signing links and documents are synthetic; replace identifiers through authorized discovery and never execute a fixture against a live organization. Binary download examples use the released SDK binary projection; tests Base64-decode and compare original bytes, lengths and server SHA-256 headers.

Supported request · Granted workspace with zero retained envelopes

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_sign.widget.get --data @payload.json --json
topolo actions plan app_topolo_sign.widget.get --resource-type workspace --resource-id "$SIGN_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_sign.widget.get --resource-type workspace --resource-id "$SIGN_WORKSPACE_ID" --data @payload.json --detail --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_sign.widget.get",
    "input": {},
    "resourceType": "workspace",
    "resourceId": "<exact granted id from discovery>",
    "detail": true
  }
}

Captured exported Worker response · HTTP 200:

{
  "success": true,
  "contractVersion": "3.0.0",
  "appId": "app_topolo_sign",
  "serviceName": "Sign",
  "generatedAt": "2026-10-05T18:07:40.412Z",
  "widgets": [
    {
      "id": "sign.workspace-summary",
      "version": "2.0.0",
      "serviceIcon": "✍️",
      "type": "stats",
      "presentation": {
        "title": "Sign workspace",
        "description": "Overview of e-signature activity, including total envelopes, pending and completed signatures, templates, and recipients awaiting action.",
        "contexts": [
          "workspace"
        ],
        "supportedSizes": [
          "compact",
          "medium",
          "wide"
        ],
        "defaultSize": "medium"
      },
      "resource": {
        "resourceType": "workspace",
        "resourceId": "ws_default",
        "requiredPermissions": [
          "workspace:read"
        ]
      },
      "state": {
        "status": "ready",
        "observedAt": "2026-10-05T18:07:40.412Z",
        "lastSuccessfulAt": "2026-10-05T18:07:40.412Z"
      },
      "refresh": {
        "intervalSeconds": 60,
        "timeoutSeconds": 10,
        "maxAgeSeconds": 60,
        "staleWhileRevalidateSeconds": 120
      },
      "configuration": {
        "allowMultipleInstances": false,
        "fields": [],
        "defaults": {}
      },
      "drilldowns": [
        {
          "id": "envelopes",
          "label": "View envelopes",
          "href": "/dashboard/envelopes"
        }
      ],
      "controls": [],
      "localization": {
        "locale": "en",
        "titleKey": "sign.widget.title",
        "descriptionKey": "sign.widget.summary"
      },
      "accessibility": {
        "label": "Sign workspace metrics",
        "description": "Overview of e-signature activity, including total envelopes, pending and completed signatures, templates, and recipients awaiting action."
      },
      "contribution": {
        "summary": "Envelope volume and signature progress for the selected Sign workspace.",
        "identity": {
          "iconSource": "catalog"
        },
        "workspaceSelector": {
          "mode": "required",
          "resourceType": "workspace",
          "label": "Sign workspace",
          "supportsMultiple": false
        },
        "metricDefinitions": [
          {
            "key": "envelopes",
            "label": "Envelopes",
            "description": "All envelopes in the workspace.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "pending",
            "label": "Pending",
            "description": "Envelopes awaiting completion.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          },
          {
            "key": "completed",
            "label": "Completed",
            "description": "Completed envelopes.",
            "unit": "count",
            "semantic": "gauge",
            "aggregation": "last"
          }
        ],
        "seriesDefinitions": [],
        "dimensions": [],
        "lifecycleStages": [
          {
            "key": "draft",
            "label": "Draft",
            "order": 0,
            "terminal": false
          },
          {
            "key": "sent",
            "label": "Sent",
            "order": 1,
            "terminal": false
          },
          {
            "key": "viewed",
            "label": "Viewed",
            "order": 2,
            "terminal": false
          },
          {
            "key": "completed",
            "label": "Completed",
            "order": 3,
            "terminal": true
          }
        ],
        "events": [
          {
            "key": "envelope_created",
            "label": "Envelope created",
            "description": "An envelope was created."
          },
          {
            "key": "envelope_sent",
            "label": "Envelope sent",
            "description": "An envelope was sent for signature."
          },
          {
            "key": "envelope_completed",
            "label": "Envelope completed",
            "description": "All required signatures were completed."
          }
        ],
        "datasets": [
          {
            "id": "signature_operations",
            "label": "Signature operations",
            "description": "Current envelope and signature-progress aggregates.",
            "grain": "One aggregate row per Sign workspace.",
            "metricKeys": [
              "envelopes",
              "pending",
              "completed"
            ],
            "seriesKeys": [],
            "dimensionKeys": [],
            "eventKeys": [
              "envelope_created",
              "envelope_sent",
              "envelope_completed"
            ],
            "actionIds": []
          }
        ],
        "compatibleVisualizations": [
          "number",
          "bar",
          "table"
        ],
        "defaultVisualization": "bar"
      },
      "metrics": [
        {
          "key": "envelopes",
          "label": "Envelopes",
          "value": 0,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-05T18:07:40.412Z",
            "end": "2026-10-05T18:07:40.412Z",
            "timezone": "UTC"
          },
          "dimensions": []
        },
        {
          "key": "pending",
          "label": "Pending",
          "value": 0,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-05T18:07:40.412Z",
            "end": "2026-10-05T18:07:40.412Z",
            "timezone": "UTC"
          },
          "dimensions": []
        },
        {
          "key": "completed",
          "label": "Completed",
          "value": 0,
          "unit": "count",
          "semantic": "gauge",
          "aggregation": "last",
          "period": {
            "start": "2026-10-05T18:07:40.412Z",
            "end": "2026-10-05T18:07:40.412Z",
            "timezone": "UTC"
          },
          "dimensions": []
        }
      ],
      "appId": "app_topolo_sign",
      "serviceName": "Sign",
      "lastUpdated": "2026-10-05T18:07:40.412Z"
    }
  ],
  "workspace": {
    "id": "ws_default",
    "name": "Fixture signing"
  },
  "workspaces": [
    {
      "id": "ws_default",
      "name": "Fixture signing",
      "isDefault": true
    }
  ]
}

HTTP 200. Inspect widgets[].resource.resourceId and workspace.id against the granted workspace. Inspect metric keys envelopes, pending and completed; all counts refer to retained workspace records.

Refused request · HTTP 401

Input · payload.json:

{}

CLI:

topolo actions validate app_topolo_sign.widget.get --data @payload.json --json
topolo actions plan app_topolo_sign.widget.get --resource-type workspace --resource-id "$SIGN_WORKSPACE_ID" --data @payload.json --json

Captured exported Worker response · HTTP 401:

{
  "error": "Token validation failed"
}

HTTP 401. Resolve the exact refusal before retrying. This request is not a successful workflow.

Verify the result

Inspect widgets[].resource.resourceId and workspace.id against the granted workspace.
Inspect metric keys envelopes, pending and completed; all counts refer to retained workspace records.

Errors and recovery

auth_error (HTTP 401): Reauthenticate in the same approved context before retrying.

Some existing refusals return a human message as error rather than a stable code; preserve the actual response, status and request id. Platform validation, authentication and resource checks can refuse before the handler.

Recovery boundary

This read changes no organizer data. Resolve identity, permission, resource binding or target state and repeat the same reviewed read. Do not turn a refused read into a mutation.