Skip to content
Ona Docs

WatchEvents

client.events.watch(EventWatchParams { environmentId, organization, resourceTypeFilters } body, RequestOptionsoptions?): EventWatchResponse { operation, resourceId, resourceType } | Stream<EventWatchResponse { operation, resourceId, resourceType } >
POST/gitpod.v1.EventService/WatchEvents

Streams events for all projects, runners, environments, tasks, and services based on the specified scope.

Use this method to:

  • Monitor resource changes in real-time
  • Track system events
  • Receive notifications

The scope parameter determines which events to watch:

  • Organization scope (default): Watch all organization-wide events including projects, runners and environments. Task and service events are not included. Use by setting organization=true or omitting the scope.
  • Environment scope: Watch events for a specific environment, including its tasks, task executions, and services. Use by setting environment_id to the UUID of the environment to watch.
ParametersExpand Collapse
body: EventWatchParams { environmentId, organization, resourceTypeFilters }
environmentId?: string

Environment scope produces events for the environment itself, all tasks, task executions, and services associated with that environment.

organization?: boolean

Organization scope produces events for all projects, runners and environments the caller can see within their organization. No task, task execution or service events are produed.

resourceTypeFilters?: Array<ResourceTypeFilter>

Filters to limit which events are delivered on organization-scoped streams. When empty, all events for the scope are delivered. When populated, only events matching at least one filter entry are forwarded. Not supported for environment-scoped streams; setting this field returns an error.

creatorIds?: Array<string>

If non-empty, only events where the resource was created by one of these user IDs are delivered. Skipped for DELETE operations (creator info is unavailable after deletion). Events with no creator information are skipped when this filter is set (fail-closed).

resourceIds?: Array<string>

If non-empty, only events for these specific resource IDs are delivered.

resourceType?: ResourceType

The resource type to filter for.

One of the following:
"RESOURCE_TYPE_UNSPECIFIED"
"RESOURCE_TYPE_ENVIRONMENT"
"RESOURCE_TYPE_RUNNER"
"RESOURCE_TYPE_PROJECT"
"RESOURCE_TYPE_TASK"
"RESOURCE_TYPE_TASK_EXECUTION"
"RESOURCE_TYPE_SERVICE"
"RESOURCE_TYPE_ORGANIZATION"
"RESOURCE_TYPE_USER"
"RESOURCE_TYPE_ENVIRONMENT_CLASS"
"RESOURCE_TYPE_RUNNER_SCM_INTEGRATION"
"RESOURCE_TYPE_HOST_AUTHENTICATION_TOKEN"
"RESOURCE_TYPE_GROUP"
"RESOURCE_TYPE_PERSONAL_ACCESS_TOKEN"
"RESOURCE_TYPE_USER_PREFERENCE"
"RESOURCE_TYPE_SERVICE_ACCOUNT"
"RESOURCE_TYPE_SECRET"
"RESOURCE_TYPE_SSO_CONFIG"
"RESOURCE_TYPE_DOMAIN_VERIFICATION"
"RESOURCE_TYPE_AGENT_EXECUTION"
"RESOURCE_TYPE_RUNNER_LLM_INTEGRATION"
"RESOURCE_TYPE_AGENT"
"RESOURCE_TYPE_ENVIRONMENT_SESSION"
"RESOURCE_TYPE_USER_SECRET"
"RESOURCE_TYPE_ORGANIZATION_POLICY"
"RESOURCE_TYPE_ORGANIZATION_SECRET"
"RESOURCE_TYPE_PROJECT_ENVIRONMENT_CLASS"
"RESOURCE_TYPE_BILLING"
"RESOURCE_TYPE_PROMPT"
"RESOURCE_TYPE_COUPON"
"RESOURCE_TYPE_COUPON_REDEMPTION"
"RESOURCE_TYPE_ACCOUNT"
"RESOURCE_TYPE_INTEGRATION"
"RESOURCE_TYPE_WORKFLOW"
"RESOURCE_TYPE_WORKFLOW_EXECUTION"
"RESOURCE_TYPE_WORKFLOW_EXECUTION_ACTION"
"RESOURCE_TYPE_SNAPSHOT"
"RESOURCE_TYPE_PREBUILD"
"RESOURCE_TYPE_ORGANIZATION_LLM_INTEGRATION"
"RESOURCE_TYPE_CUSTOM_DOMAIN"
"RESOURCE_TYPE_ROLE_ASSIGNMENT_CHANGED"
"RESOURCE_TYPE_GROUP_MEMBERSHIP_CHANGED"
"RESOURCE_TYPE_WEBHOOK"
"RESOURCE_TYPE_SCIM_CONFIGURATION"
"RESOURCE_TYPE_SERVICE_ACCOUNT_SECRET"
"RESOURCE_TYPE_ANNOUNCEMENT_BANNER"
"RESOURCE_TYPE_SERVICE_ACCOUNT_TOKEN"
"RESOURCE_TYPE_ROLE_ASSIGNMENT"
"RESOURCE_TYPE_WARM_POOL"
"RESOURCE_TYPE_NOTIFICATION"
ReturnsExpand Collapse
EventWatchResponse { operation, resourceId, resourceType }
operation?: ResourceOperation
One of the following:
"RESOURCE_OPERATION_UNSPECIFIED"
"RESOURCE_OPERATION_CREATE"
"RESOURCE_OPERATION_UPDATE"
"RESOURCE_OPERATION_DELETE"
"RESOURCE_OPERATION_UPDATE_STATUS"
resourceId?: string
formatuuid
resourceType?: ResourceType
One of the following:
"RESOURCE_TYPE_UNSPECIFIED"
"RESOURCE_TYPE_ENVIRONMENT"
"RESOURCE_TYPE_RUNNER"
"RESOURCE_TYPE_PROJECT"
"RESOURCE_TYPE_TASK"
"RESOURCE_TYPE_TASK_EXECUTION"
"RESOURCE_TYPE_SERVICE"
"RESOURCE_TYPE_ORGANIZATION"
"RESOURCE_TYPE_USER"
"RESOURCE_TYPE_ENVIRONMENT_CLASS"
"RESOURCE_TYPE_RUNNER_SCM_INTEGRATION"
"RESOURCE_TYPE_HOST_AUTHENTICATION_TOKEN"
"RESOURCE_TYPE_GROUP"
"RESOURCE_TYPE_PERSONAL_ACCESS_TOKEN"
"RESOURCE_TYPE_USER_PREFERENCE"
"RESOURCE_TYPE_SERVICE_ACCOUNT"
"RESOURCE_TYPE_SECRET"
"RESOURCE_TYPE_SSO_CONFIG"
"RESOURCE_TYPE_DOMAIN_VERIFICATION"
"RESOURCE_TYPE_AGENT_EXECUTION"
"RESOURCE_TYPE_RUNNER_LLM_INTEGRATION"
"RESOURCE_TYPE_AGENT"
"RESOURCE_TYPE_ENVIRONMENT_SESSION"
"RESOURCE_TYPE_USER_SECRET"
"RESOURCE_TYPE_ORGANIZATION_POLICY"
"RESOURCE_TYPE_ORGANIZATION_SECRET"
"RESOURCE_TYPE_PROJECT_ENVIRONMENT_CLASS"
"RESOURCE_TYPE_BILLING"
"RESOURCE_TYPE_PROMPT"
"RESOURCE_TYPE_COUPON"
"RESOURCE_TYPE_COUPON_REDEMPTION"
"RESOURCE_TYPE_ACCOUNT"
"RESOURCE_TYPE_INTEGRATION"
"RESOURCE_TYPE_WORKFLOW"
"RESOURCE_TYPE_WORKFLOW_EXECUTION"
"RESOURCE_TYPE_WORKFLOW_EXECUTION_ACTION"
"RESOURCE_TYPE_SNAPSHOT"
"RESOURCE_TYPE_PREBUILD"
"RESOURCE_TYPE_ORGANIZATION_LLM_INTEGRATION"
"RESOURCE_TYPE_CUSTOM_DOMAIN"
"RESOURCE_TYPE_ROLE_ASSIGNMENT_CHANGED"
"RESOURCE_TYPE_GROUP_MEMBERSHIP_CHANGED"
"RESOURCE_TYPE_WEBHOOK"
"RESOURCE_TYPE_SCIM_CONFIGURATION"
"RESOURCE_TYPE_SERVICE_ACCOUNT_SECRET"
"RESOURCE_TYPE_ANNOUNCEMENT_BANNER"
"RESOURCE_TYPE_SERVICE_ACCOUNT_TOKEN"
"RESOURCE_TYPE_ROLE_ASSIGNMENT"
"RESOURCE_TYPE_WARM_POOL"
"RESOURCE_TYPE_NOTIFICATION"

WatchEvents

import Gitpod from '@gitpod/sdk';

const client = new Gitpod({
  bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted
});

const response = await client.events.watch();

console.log(response.operation);
Returns Examples