> ## Documentation Index > Fetch the complete documentation index at: https://docs.credibledata.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a run ## OpenAPI ````yaml /controlplane-public-api-doc.yaml get /organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/runs/{runId} openapi: 3.1.0 info: title: Credible Admin API description: > The Credible Admin API is a comprehensive REST API that empowers organizations to manage their Malloy data modeling ecosystem with enterprise-grade security and governance. This API provides programmatic access to all administrative functions, enabling seamless integration with existing workflows and automation systems. ## Key Features - **Organization Management**: Create and manage organizations with fine-grained access controls - **Environment & Package Lifecycle**: Full CRUD operations for environments, packages, and versions - **Connection Management**: Secure database connection configuration and management - **Permission Management**: Granular role-based access control (RBAC) at organization, environment, package, workspace, and document levels - **Workspace Management**: Collaborative workspaces for data modeling and analysis - **User & Group Management**: Comprehensive user administration with group-based permissions ## Resource Hierarchy The API follows a hierarchical resource structure with fine-grained permission management at each level: ``` Organizations ├── Permissions ├── Environments │ ├── Permissions │ ├── Packages │ │ ├── Permissions │ │ └── Versions │ └── Connections ├── Workspaces │ ├── Permissions │ └── Documents │ └── Permissions └── Groups ├── Permissions └── Members System-Level Resources: ├── Users ├── System Permissions └── Demo Operations ``` ## Authentication & Authorization All API endpoints require proper authentication. The API implements fine-grained authorization using role-based permissions: - **Admin**: Full access to all resources within scope - **Modeler**: Can create and modify data models and packages - **Viewer**: Read-only access to resources - **Manager**: Workspace management capabilities - **Editor**: Document editing permissions ## Rate Limiting & Best Practices - API requests are rate-limited to ensure system stability - Implement proper error handling and retry logic - Cache responses when appropriate to reduce API calls ## Support & Documentation For additional support, examples, and integration guides, visit our developer documentation or contact our support team. version: v0 contact: name: Credible Support email: support@credibledata.com url: https://credibledata.com/support license: name: Proprietary url: https://credibledata.com/license termsOfService: https://credibledata.com/terms servers: - url: https://{organization}.admin.credibledata.com/api/v0/ description: Production API server variables: organization: default: demo description: Your organization subdomain security: - bearerAuth: [] tags: - name: organizations description: >- Organization management operations for creating, updating, and managing organizational entities - name: organizationPermissions description: >- Fine-grained permission management for organizations, including role assignments and access controls - name: environments description: >- Environment lifecycle management including creation, configuration, and deletion of data modeling environments - name: environmentPermissions description: >- Permission management for environments, controlling access to environment resources and capabilities - name: packages description: >- Package management for Malloy data models, including versioning, publishing, and distribution - name: packagePermissions description: >- Access control for packages, managing who can view, modify, or publish package versions - name: versions description: >- Version management for packages, including archiving, status updates, and lifecycle management - name: connections description: >- Database connection management for secure data source configuration and access - name: materializations description: >- Malloy Persistence materializations (per-version serving anchors for persisted sources) - name: indexes description: >- Malloy Persistence dimensional search indexes (per-version serving anchors for indexed dimensions) - name: runs description: >- Malloy Persistence build/refresh runs — one package-level build event carrying typed units (materialized sources + built indexes) - name: workspaces description: >- Collaborative workspace management for team-based data modeling and analysis - name: workspacePermissions description: >- Access control for workspaces, managing who can view, manage, or collaborate in workspaces - name: documents description: >- Document management within workspaces, including workbooks, dashboards, and other content - name: documentPermissions description: >- Access control for documents, managing who can view, edit, or share document content - name: groups description: >- User group management for organizing users and managing group-based permissions - name: users description: >- User account management including creation, updates, and profile management - name: demo description: Demo and self-service operations for quick setup and testing scenarios - name: permissions description: System-level permission management for administrative functions - name: bookmarks description: >- User bookmark management for saving references to workspaces, models, and chats - name: attributes description: Trusted user attributes for fine-grain (row/column-level) access control - name: invites description: >- Organization-creation invite tokens. A super-admin mints tokens one per call (call `POST /invites` repeatedly to populate an outreach campaign); each token can be redeemed once by an authenticated user to create a new organization on the fly. paths: /organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/runs/{runId}: get: tags: - runs summary: Get a run operationId: getRun parameters: - name: organizationName in: path required: true description: The unique identifier of the organization schema: $ref: '#/components/schemas/IdentifierPattern' - name: environmentName in: path required: true description: The unique identifier of the environment schema: $ref: '#/components/schemas/IdentifierPattern' - name: packageName in: path required: true description: The unique identifier of the package schema: $ref: '#/components/schemas/IdentifierPattern' - name: runId in: path required: true description: The unique identifier of the run schema: type: string responses: '200': description: Run retrieved successfully content: application/json: schema: $ref: '#/components/schemas/Run' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: schemas: IdentifierPattern: type: string pattern: ^[a-zA-Z0-9_ -]+$ description: Standard identifier pattern for resource names Run: type: object description: > A package-level build/refresh event (version-independent) — the single, unified run resource. It records the requested scope and correlates the dispatch; its concrete units are the typed artifacts it produced — materialized sources (source nodes) and built indexes (index nodes) — surfaced in the run's build plan (`buildPlan.nodes`/`edges`, populated on `getRun`). A run defaults to a full run spanning both families — a publish, an on-demand rebuild, and a scheduled re-materialization all refresh a version's tables and its indexes — but may also be scoped to a single unit (Phase C per-unit dispatch). Each produced unit advances its own serving pointer independently, so a partial failure leaves the run READY while the failed unit carries its own error. properties: id: type: string buildNumber: type: integer description: > Stable, 1-based build ordinal within the **package** — the "Build gNNN" the UI shows (zero-padded for display). Monotonic per package, assigned at run creation. This is the run build number, NOT the per-source physical table generation (the g in a materialized table name), which counts per-source rebuilds and diverges under reuse. Null only for legacy runs created before the number existed. trigger: type: string enum: - PUBLISH - ON_DEMAND - SCHEDULER status: type: string description: > Run lifecycle status, rolled up from the units it produced. Non-terminal: BUILDING. Terminal: READY, FAILED, CANCELLED. A run is READY once every produced unit is terminal; individual unit failures are carried per node in the run's build plan (`buildPlan.nodes`, on `getRun`). enum: - BUILDING - READY - FAILED - CANCELLED targetSourceName: type: string description: >- Requested target source (Phase C per-unit dispatch). Null on a whole-version run (the createRun default); set when createRun scoped the run to a single source via the sourceName selector. A null component widens to the whole package. targetDimension: type: string description: >- Requested target dimension (Phase C per-unit dispatch). Null on a whole-version run; set when createRun scoped the run to a single indexed dimension via the dimension selector. targetModelFilePath: type: string description: >- Requested target model file (Phase C per-unit dispatch). Null on a whole-version run; disambiguates a dimension defined in more than one model file when the modelFilePath selector is set. targetIncludeUpstream: type: boolean description: | The scoped rerun's upstream choice (Phase C). Only meaningful with `targetSourceName`/`targetDimension`: when true, the rerun also force-rebuilt the target's transitive upstream persisted closure (rather than reusing those upstream tables); false / absent = the target alone (a source references its upstreams, an index reuses its source table). Always false on a whole-version run. triggeringVersionId: type: string description: > The version this run was started for — the version whose publish drove a PUBLISH run, the version an on-demand full run rebuilds, or the version a scheduled re-materialization refreshes. Provenance only: the run itself is package-scoped and may impact other versions that bind the same dimension. Null only for a future package-level scoped refresh with no single initiating version. buildPlan: $ref: '#/components/schemas/RunBuildPlan' startedAt: type: string format: date-time completedAt: type: string format: date-time error: type: string description: >- Run-level failure reason (planning/orchestration failure); per-unit failures live on the produced units. createdAt: type: string format: date-time updatedAt: type: string format: date-time RunBuildPlan: type: object description: > A run's build plan across both unit families. Two layers: 1. A diagnostic **summary** (counters + name lists): how many persist sources (table units) and indexed dimensions (index units) it planned, and their outcomes. Always populated (on both `listRuns` and `getRun`). 2. A stateful **dependency graph** (`nodes` + `edges`): one node per source (materialized table) and per indexed dimension, each carrying that unit's live state, wired source -> index. Populated on `getRun` only; null on `listRuns` to keep the list payload small (mirrors how `Version.buildPlan` is `getVersion`-only). This graph is the single source of truth for a run's units — the internal content address (entity_id) is never exposed. properties: sourceCount: type: integer description: Number of persist sources (table units) in the run's build plan. builtSources: type: array description: Sources that produced a fresh table this run. items: type: string reusedSources: type: array description: >- Sources whose existing table was reused this run (their definition and inputs were unchanged, so no rebuild was needed). items: type: string unsupportedSources: type: array description: >- Sources skipped because the connection dialect can't materialize them. items: type: string failedSources: type: object description: Source name -> failure reason, for sources that errored this run. additionalProperties: type: string dimensionCount: type: integer description: >- Number of indexed dimensions (index units) this run produced/refreshed. builtDimensions: type: array description: Dimensions that produced a READY index this run. items: type: string failedDimensions: type: object description: Dimension -> failure reason, for dimensions that failed this run. additionalProperties: type: string nodes: type: array description: > The build plan's stateful graph nodes: one per source (materialized table) and per indexed dimension, each carrying that unit's live state. Populated on `getRun` only; null/absent on `listRuns`. items: $ref: '#/components/schemas/RunBuildPlanNode' edges: type: array description: > Dependency edges over `nodes`, keyed by node `key`. Carries source -> index edges (each indexed dimension depends on its owning source) and source -> source table lineage (from the run's durable build plan's derivation DAG). Populated on `getRun` only; null/absent on `listRuns`. items: $ref: '#/components/schemas/RunBuildPlanEdge' Error: type: object x-model-name: ModelError description: Standard error response format used across all API endpoints properties: code: type: string description: > Machine-readable error code that identifies the specific error condition. Clients should branch on `code`, not on the human-readable `message` — the message text is informational and may change over time. Generic codes (may appear on any endpoint): - `VALIDATION_ERROR`: Request body or path/query parameter failed validation - `AUTHENTICATION_REQUIRED`: Valid authentication is required - `INSUFFICIENT_PERMISSIONS`: User lacks required permissions - `RESOURCE_NOT_FOUND`: Requested resource does not exist - `CONFLICT`: Generic resource state conflict (used when no more specific code applies) - `RATE_LIMIT_EXCEEDED`: API rate limit exceeded - `INTERNAL_ERROR`: Unexpected server error Endpoint-specific codes used by the signup / invites flow: - `ORGANIZATION_NAME_TAKEN`: 409 on `POST /organizations` — the requested org name (URL slug) is already in use. Retry with a different name. - `ORGANIZATION_NAME_RESERVED`: 409 on `POST /organizations` — the requested org name collides with a platform subdomain (e.g. `signup`, `admin`, `data`, `login`) and cannot be claimed. Retry with a different name. - `INVITE_ALREADY_CONSUMED`: 409 on `POST /organizations` — the supplied invite token has already been redeemed into an existing organization. Retry will not help; the token is dead. - `INVITE_ALREADY_CONSUMED_REVOKE`: 409 on `DELETE /invites/{token}` — consumed invites are preserved for audit and cannot be revoked. - `INVITE_INVALID`: 400 on `POST /organizations` — the supplied invite token is malformed or unknown. - `INVITE_EXPIRED`: 400 on `POST /organizations` — the supplied invite token is past its `expiresAt`. - `INVITE_EMAIL_MISMATCH`: 403 on `POST /organizations` — the invite is bound to a different email address than the caller. message: type: string description: Human-readable error message providing details about what went wrong RunBuildPlanNode: type: object description: > One node in a run's build-plan graph, discriminated by `nodeType`. A SOURCE node is a persist source (materialized when this run produced a physical table for it); an INDEX node is a built index for one `(source, dimension)`. Carries the unit's live state; fields not relevant to a node's type are null. The internal content address (entity_id) is never exposed. properties: key: type: string description: > Stable within-graph identity used by `RunBuildPlanEdge`. Source nodes are keyed by source name; index nodes by their `source.dimension (modelFile)` coordinate — so a discovered-but-not-yet-built dimension still has a key. id: type: string description: > The backing record's UUID (materialized table or index anchor/artifact), for deep-linking. Null for a discovered dimension with no artifact yet. nodeType: type: string description: >- Which family this node is — SOURCE (materialized source) or INDEX (built index). enum: - SOURCE - INDEX sourceName: type: string description: >- The persist source (SOURCE) or the source that owns the dimension (INDEX). status: type: string description: > Per-run WORK lifecycle for this node — the state of the work THIS run does on it, not the underlying artifact's steady state. PENDING: the run is in flight and this unit's build hasn't started. BUILDING: this run is actively (re)materializing/(re)indexing it. DONE: this run's build committed (or, on a full run, reaffirmed an unchanged artifact). FAILED: this run's build errored (see `error`). A scoped rerun's graph carries only the units it works on, so every node walks PENDING -> BUILDING -> DONE/FAILED as the run progresses. enum: - PENDING - BUILDING - DONE - FAILED materialized: type: boolean description: > SOURCE nodes only. True when this run produced a physical table for the source; false for a source that only surfaces via an indexed dimension (e.g. a live/non-persisted twin) so its index nodes aren't orphaned. tableName: type: string description: > Physical table name of the materialized source, an immutable generation (e.g. orders_ab12_v3). SOURCE nodes only; null for INDEX nodes. modelFilePath: type: string description: > The model file this dimension was discovered under, to distinguish two same-named dimensions from different files. INDEX nodes only. dimension: type: string description: >- The indexed dimension path (e.g. "country" or "people.name"). INDEX nodes only; null for SOURCE nodes. rowCount: type: integer format: int64 description: >- Indexed value count, reported by the pipeline on completion. INDEX nodes only; null until READY or for SOURCE nodes. lastIndexedAt: type: string format: date-time description: >- When this index generation finished building. INDEX nodes only; null until READY or for SOURCE nodes. error: type: string description: Failure reason when a node's unit failed; null otherwise. createdAt: type: string format: date-time updatedAt: type: string format: date-time RunBuildPlanEdge: type: object description: >- A dependency edge over the run's build-plan nodes — "from" must be built before "to". properties: from: type: string description: Upstream node `key` (a dependency, e.g. a source). to: type: string description: >- Downstream node `key` that depends on "from" (e.g. an index on that source). responses: BadRequest: description: >- The request was malformed or can not be performed given the state of the system. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- Can not perform the operation due to insufficient permissions or the state of the system. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The specified resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````