## ListPrebuilds **post** `/gitpod.v1.PrebuildService/ListPrebuilds` ListPrebuilds ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { creatorIds, executorIds, phases, 2 more }` filter contains the filter options for listing prebuilds - `creatorIds: optional array of string` creator_ids filters prebuilds by who created them - `executorIds: optional array of string` executor_ids filters prebuilds by whose credentials were used to run them - `phases: optional array of PrebuildPhase` phases filters prebuilds by their current phase - `"PREBUILD_PHASE_UNSPECIFIED"` - `"PREBUILD_PHASE_PENDING"` - `"PREBUILD_PHASE_STARTING"` - `"PREBUILD_PHASE_RUNNING"` - `"PREBUILD_PHASE_STOPPING"` - `"PREBUILD_PHASE_SNAPSHOTTING"` - `"PREBUILD_PHASE_COMPLETED"` - `"PREBUILD_PHASE_FAILED"` - `"PREBUILD_PHASE_CANCELLING"` - `"PREBUILD_PHASE_CANCELLED"` - `"PREBUILD_PHASE_DELETING"` - `"PREBUILD_PHASE_DELETED"` - `projectIds: optional array of string` project_ids filters prebuilds to specific projects - `triggeredBy: optional array of PrebuildTrigger` triggered_by filters prebuilds by how they were triggered - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` - `pagination: optional object { token, pageSize }` pagination contains the pagination options for listing prebuilds - `token: optional string` Token for the next set of results that was returned as next_token of a PaginationResponse - `pageSize: optional number` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `pagination: optional object { nextToken }` pagination contains the pagination response - `nextToken: optional string` Token passed for retrieving the next set of results. Empty if there are no more results - `prebuilds: optional array of Prebuild` prebuilds are the prebuilds that matched the query - `metadata: PrebuildMetadata` metadata contains organizational and ownership information - `createdAt: string` created_at is when the prebuild was created - `creator: Subject` creator is the identity of who created the prebuild. For manual prebuilds, this is the user who triggered it. For scheduled prebuilds, this is the configured executor. - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `updatedAt: string` updated_at is when the prebuild was last updated - `environmentClassId: optional string` environment_class_id is the environment class used to create this prebuild. While the prebuild is created with a specific environment class, environments with different classes (e.g., smaller or larger instance sizes) can be created from the same prebuild, as long as they run on the same runner. If not specified in create requests, uses the project's default environment class. - `executor: optional Subject` executor is the identity used to run the prebuild. The executor's SCM credentials are used to clone the repository. If not set, the creator's identity is used. - `organizationId: optional string` organization_id is the ID of the organization that owns the prebuild - `projectId: optional string` project_id is the ID of the project this prebuild was created for - `triggeredBy: optional PrebuildTrigger` trigger describes the trigger that created this prebuild. - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` - `spec: PrebuildSpec` spec contains the configuration used to create this prebuild - `desiredPhase: optional PrebuildPhase` desired_phase is the desired phase of the prebuild. Used to signal cancellation or other state changes. This field is managed by the API and reconciler. - `"PREBUILD_PHASE_UNSPECIFIED"` - `"PREBUILD_PHASE_PENDING"` - `"PREBUILD_PHASE_STARTING"` - `"PREBUILD_PHASE_RUNNING"` - `"PREBUILD_PHASE_STOPPING"` - `"PREBUILD_PHASE_SNAPSHOTTING"` - `"PREBUILD_PHASE_COMPLETED"` - `"PREBUILD_PHASE_FAILED"` - `"PREBUILD_PHASE_CANCELLING"` - `"PREBUILD_PHASE_CANCELLED"` - `"PREBUILD_PHASE_DELETING"` - `"PREBUILD_PHASE_DELETED"` - `specVersion: optional string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `timeout: optional string` timeout is the maximum time allowed for the prebuild to complete. Defaults to 60 minutes if not specified. Maximum allowed timeout is 2 hours. - `status: PrebuildStatus` status contains the current status and progress of the prebuild - `phase: PrebuildPhase` phase is the current phase of the prebuild lifecycle - `completionTime: optional string` completion_time is when the prebuild completed (successfully or with failure) - `environmentId: optional string` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `failureMessage: optional string` failure_message contains details about why the prebuild failed - `logUrl: optional string` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `snapshotCompletionPercentage: optional number` snapshot_completion_percentage is the progress of snapshot creation (0-100). Only populated when phase is SNAPSHOTTING and progress is available from the cloud provider. This value may update infrequently or remain at 0 depending on the provider. - `snapshotSizeBytes: optional string` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `statusVersion: optional string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `warningMessage: optional string` warning_message contains warnings from the prebuild environment that indicate something went wrong but the prebuild could still complete. For example, the devcontainer failed to build but the environment is still usable. These warnings will likely affect any environment started from this prebuild. - `id: optional string` id is the unique identifier for the prebuild ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/ListPrebuilds \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "prebuilds": [ { "metadata": { "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "updatedAt": "2019-12-27T18:11:19.117Z", "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "executor": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "triggeredBy": "PREBUILD_TRIGGER_UNSPECIFIED" }, "spec": { "desiredPhase": "PREBUILD_PHASE_UNSPECIFIED", "specVersion": "specVersion", "timeout": "+9125115.360s" }, "status": { "phase": "PREBUILD_PHASE_UNSPECIFIED", "completionTime": "2019-12-27T18:11:19.117Z", "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "failureMessage": "failureMessage", "logUrl": "https://example.com", "snapshotCompletionPercentage": 100, "snapshotSizeBytes": "snapshotSizeBytes", "statusVersion": "statusVersion", "warningMessage": "warningMessage" }, "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } ] } ```