Skip to content
Ona API Reference
Ona Docs
API Reference
Events

WatchEvents

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.
Body ParametersExpand Collapse
environmentId: optional string

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

organization: optional 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: optional array of object { creatorIds, resourceIds, resourceType }

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: optional array of 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: optional array of string

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

resourceType: 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
operation: optional ResourceOperation
One of the following:
"RESOURCE_OPERATION_UNSPECIFIED"
"RESOURCE_OPERATION_CREATE"
"RESOURCE_OPERATION_UPDATE"
"RESOURCE_OPERATION_DELETE"
"RESOURCE_OPERATION_UPDATE_STATUS"
resourceId: optional string
formatuuid
resourceType: 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

curl https://app.gitpod.io/api/gitpod.v1.EventService/WatchEvents \
    -H 'Content-Type: application/jsonl' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
Returns Examples