--- title: "List Plays" method: GET path: "/api/plays" tags: ["plays"] --- # List Plays `GET /api/plays` ## Request - Base URL: `https://platform.verbiflow.com/api/bridge` - URL: `https://platform.verbiflow.com/api/bridge/api/plays` - Auth: one of: - HTTP bearer and API key in header `x-flage-org-id` - HTTP bearer and API key in header `x-flage-org-slug` ## Query parameters - `include_hidden` boolean - `title` string, nullable - `q` string, nullable ## Response `200` Successful Response - PlayListResponse - `plays` PlayRecord[], required: Play records visible to the selected workspace. - `billing_summary` PlayBillingSummary: Unified customer credit accounting for one Play, including partial-evidence status. - `by_capability` PlayBillingCapability[], required: Credit usage grouped by capability and billing owner. - `capability_id` string, required: Stable capability responsible for the measured credit usage. - `cost` string, required: Credits attributed to this capability; this value is not provider cost or dollars. - `credits_used` string, required: Customer credits attributed to this record. - `event_count` integer, required: Number of accounting events contributing to this aggregate. - `owner` string, required: Billing owner of this credit usage. - `units` string, required: Customer credit units attributed to this capability. - `usage_units` string, required: Legacy alias of customer credits used. - `by_owner` PlayBillingOwner[], required: Credit usage grouped by billing owner. - `credits_used` string, required: Customer credits attributed to this record. - `event_count` integer, required: Number of accounting events contributing to this aggregate. - `owner` string, required: Billing owner of this credit usage. - `credits_consumed` union, required: Consumed customer credits; exact decimal string, or numeric zero in older empty summaries. - string - number - `credits_reserved` union, required: Reserved customer credits; exact decimal string, or numeric zero in older empty summaries. - string - number - `credits_used` union, required: Customer credits attributed to this record. - string - number - `event_count` integer, required: Number of accounting events contributing to this aggregate. - `is_partial` boolean, required: Whether accounting evidence is incomplete and the totals require qualification. - `partial_reason` string, nullable, required: Reason totals are partial, or null for a complete summary. - `play_id` string, required: Canonical workspace-scoped Play id. - `scope` 'unified_credit_meter', required: Accounting or presentation scope selected by the producer. - `total_cost` union, required: Legacy alias of customer credits used; this is not provider cost or dollars. - string - number - `total_units` union, required: Legacy alias of customer credits used. - string - number - `usage_units` union, required: Legacy alias of customer credits used. - string - number - `content_type` string, nullable: Stored bundle media type. - `created_at` string, required: ISO 8601 Play creation time. - `description` string, nullable, required: Optional human-facing Play description. - `entrypoint_path` string, nullable: Verified bundle entrypoint path. - `file_count` integer, nullable: Number of files in the stored revision. - `filename` string, nullable: Original uploaded bundle filename. - `has_thumbnail` boolean, nullable: Whether a thumbnail artifact exists. - `id` string, required: Canonical Play id. - `kind` 'workflow_play' | 'static_bundle', required: Stored workflow or uploaded static bundle kind. - `last_error` PlayError: Known error fields plus sanitized producer-specific diagnostic data. - `code` string: Stable sanitized error code when the producer supplied one. - `message` string: Sanitized human-facing explanation. - `latest_run` PlayRunSummary: Catalog-visible lifecycle and timing of one canonical Play run. - `approval` PlayRunApproval: Sanitized approval presented alongside a blocked Play run. - `approval_id` string, required: Durable pending approval id. - `choices` PlayApprovalChoice[], required: Available member decisions for this pending approval. - `id` string, required: Durable identifier within the owning Play or run. - `label` string, required: Human-facing label. - `details` object, required: Effect-specific sanitized JSON evidence for the requested decision. - `message` string, required: Sanitized human-facing explanation. - `completed_at` string, nullable, required: ISO 8601 completion time, or null while incomplete. - `duration_seconds` number, nullable, required: Recorded elapsed duration in seconds, or null when unavailable. - `final_row_count` integer, required: Published final row count for this run. - `id` string, required: Durable identifier within the owning Play or run. - `mode` string, required: Persisted execution mode. - `primary_output` PlayPrimaryOutput: Display-only primary result summary; full outputs own read references. - `description` string, nullable, required: Optional human-facing description. - `id` string, required: Durable identifier within the owning Play or run. - `label` string, required: Human-facing label. - `row_count` integer, nullable, required: Published output row count when applicable, or null. - `revision_id` string, nullable, required: Immutable Play revision id. - `snapshot_state` string, required: Publication state of this snapshot: draft, diagnostic or final. - `source_window_label` string, required: Human-facing source-window description for the run. - `started_at` string, required: ISO 8601 start time recorded for this execution. - `status` string, required: Lifecycle state recorded by the owning operation. - `trigger` PlayRunTrigger, required: Admission source retained with the canonical Play run. - `kind` string, required: Producer-defined classification of this record. - `trigger_id` string, nullable, required: Durable trigger or schedule id when one exists, or null. - `local_root_label` string, nullable: Portable label for the authored local root. - `operation_summary` PlayOperationSummary: Presentation fields plus the scheduled executor's Play-defined terminal summary. - `latest_error` PlayError: Known error fields plus sanitized producer-specific diagnostic data. - `code` string: Stable sanitized error code when the producer supplied one. - `message` string: Sanitized human-facing explanation. - `pending_approvals_count` integer: Number of pending member decisions in the presentation summary. - `runtime_state` string: Latest runtime state reported by synchronization or execution. - `snapshot_state` string: Publication state of this snapshot: draft, diagnostic or final. - `sync_state` PlaySyncState: Synchronization metadata; registration may attach portable JSON extensions. - `auto_sync` boolean: Whether the authoring root requested automatic synchronization. - `code_sync_state` string: Current state of code revision synchronization. - `is_stale` boolean: Whether the latest local runtime snapshot is considered stale. - `last_snapshot_at` string: ISO 8601 time of the last accepted local runtime snapshot. - `latest_code_archive_sha256` string: SHA-256 of the latest synchronized source archive. - `latest_code_revision_id` string: Latest synchronized immutable source revision id. - `latest_code_source_hash` string: Semantic digest of the latest synchronized source tree. - `latest_code_synced_at` string: ISO 8601 time of the latest source synchronization. - `latest_revision_digest` string: Canonical digest of the latest published executor specification. - `latest_revision_id` string: Latest immutable published Play revision id. - `latest_revision_kind` 'prompt' | 'workflow': Executor kind of the latest immutable revision. - `local_root_label` string: Portable label of the editable authoring root. - `runtime_state` string: Latest runtime state reported by synchronization or execution. - `snapshot_state` string: Publication state of this snapshot: draft, diagnostic or final. - `output_count` integer, nullable: Count of published Play output artifacts. - `owner_email` string, nullable, required: Current email of the Play owner. - `owner_id` string, required: Workspace member id that owns the Play. - `owner_name` string, nullable, required: Current display name of the Play owner. - `run_count` integer, nullable: Count of admitted Play runs visible to this workspace. - `sdk_version` string, nullable: SDK version pinned by the current code revision. - `size_bytes` integer, nullable: Stored source or bundle byte size. - `sync_state` PlaySyncState: Synchronization metadata; registration may attach portable JSON extensions. - `auto_sync` boolean: Whether the authoring root requested automatic synchronization. - `code_sync_state` string: Current state of code revision synchronization. - `is_stale` boolean: Whether the latest local runtime snapshot is considered stale. - `last_snapshot_at` string: ISO 8601 time of the last accepted local runtime snapshot. - `latest_code_archive_sha256` string: SHA-256 of the latest synchronized source archive. - `latest_code_revision_id` string: Latest synchronized immutable source revision id. - `latest_code_source_hash` string: Semantic digest of the latest synchronized source tree. - `latest_code_synced_at` string: ISO 8601 time of the latest source synchronization. - `latest_revision_digest` string: Canonical digest of the latest published executor specification. - `latest_revision_id` string: Latest immutable published Play revision id. - `latest_revision_kind` 'prompt' | 'workflow': Executor kind of the latest immutable revision. - `local_root_label` string: Portable label of the editable authoring root. - `runtime_state` string: Latest runtime state reported by synchronization or execution. - `snapshot_state` string: Publication state of this snapshot: draft, diagnostic or final. - `title` string, required: Human-facing Play title. - `updated_at` string, required: ISO 8601 last metadata update time. - `visibility` 'visible' | 'local_only', nullable: Workspace catalog visibility. - `workflow_name` string, nullable: Declared SDK workflow name. - `workflow_slug` string, nullable: Stable SDK workflow slug. ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract.md) - [All operations](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/llms.txt) - [OpenAPI document](https://skmtc.dev/verbiflow/apis/verbiflow-sdk-http-contract/revisions/c80e903ef8f3?raw)