Skip to content
Ona API Reference
Ona Docs
API Reference
Events

WatchEvents

events.watch(EventWatchParams**kwargs) -> EventWatchResponse
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
environment_id: Optional[str]

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

organization: Optional[bool]

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.

resource_type_filters: Optional[Iterable[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.

creator_ids: Optional[Sequence[str]]

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).

resource_ids: Optional[Sequence[str]]

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

resource_type: Optional[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
class EventWatchResponse: …
operation: Optional[ResourceOperation]
One of the following:
"RESOURCE_OPERATION_UNSPECIFIED"
"RESOURCE_OPERATION_CREATE"
"RESOURCE_OPERATION_UPDATE"
"RESOURCE_OPERATION_DELETE"
"RESOURCE_OPERATION_UPDATE_STATUS"
resource_id: Optional[str]
formatuuid
resource_type: Optional[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 os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
for event in client.events.watch():
  print(event)
Returns Examples