> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Watch Events
> Streams events for all projects, runners, environments, tasks, and services based on the
`Server streaming` ยท [`Events`](/docs/api-reference/generated/event/overview)
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.
## Endpoint
```text theme={null}
POST /api/gitpod.v1.EventService/WatchEvents
```
Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.
## Request example
This is a streaming RPC. Use a Connect client so it can frame messages with `application/connect+json` or `application/connect+proto`. The JSON below is the unframed request message.
```python Python theme={null}
import gitpod.v1.event_pb2 as event_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = event_pb2.WatchEventsRequest(
organization=True,
)
for response in ona.services.event.watch_events(request):
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { WatchEventsRequestSchema } from "@gitpod/sdk/gitpod/v1/event_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(WatchEventsRequestSchema, {
scope: {
case: "organization",
value: true,
},
});
for await (const response of ona.services.event.watchEvents(request)) {
console.log(response);
}
}
main().catch(console.error);
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
"connectrpc.com/connect"
"github.com/gitpod-io/gitpod-sdk-go/sdk"
gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
)
func main() {
ona, err := sdk.NewFromEnv()
if err != nil {
log.Fatal(err)
}
request := connect.NewRequest(&gitpodpb.WatchEventsRequest{
Scope: &gitpodpb.WatchEventsRequest_Organization{
Organization: true,
},
})
stream, err := ona.Services.Event.WatchEvents(context.Background(), request)
if err != nil {
log.Fatal(err)
}
for stream.Receive() {
fmt.Println(stream.Msg())
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
}
```
```json Request body theme={null}
{
"organization": true
}
```
## Request
`gitpod.v1.WatchEventsRequest`
| Field | Type | Required | Description |
| --------------------- | ---------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organization` | boolean | No | 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. |
| `environmentId` | string | No | Environment scope produces events for the environment itself, all tasks, task executions, and services associated with that environment. |
| `resourceTypeFilters` | array of [ResourceTypeFilter](#type-gitpod-v1-watch-events-request-resource-type-filter) | No | 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. Constraints: `repeated.max_items=50`. |
## Response
`gitpod.v1.WatchEventsResponse`
| Field | Type | Required | Description |
| -------------- | ------------------------------------------------------- | -------- | -------------------------------- |
| `operation` | [ResourceOperation](#enum-gitpod-v1-resource-operation) | No | |
| `resourceType` | [ResourceType](#enum-gitpod-v1-resource-type) | No | |
| `resourceId` | string | No | Constraints: `string.uuid=true`. |
## Related types
ResourceTypeFilter restricts which events are delivered for a specific resource type.
`gitpod.v1.WatchEventsRequest.ResourceTypeFilter`
| Field | Type | Required | Description |
| -------------- | --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resourceType` | [ResourceType](#enum-gitpod-v1-resource-type) | No | The resource type to filter for. Constraints: `enum.defined_only=true, enum.not_in=0`. |
| `resourceIds` | array of string | No | If non-empty, only events for these specific resource IDs are delivered. Constraints: `repeated.items.string.uuid=true, repeated.max_items=25`. |
| `creatorIds` | array of string | No | 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). Constraints: `repeated.items.string.uuid=true, repeated.max_items=25`. |
| Value | Number | Description |
| ---------------------------------- | -----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RESOURCE_OPERATION_UNSPECIFIED` | 0 | |
| `RESOURCE_OPERATION_CREATE` | 1 | |
| `RESOURCE_OPERATION_UPDATE` | 2 | |
| `RESOURCE_OPERATION_DELETE` | 3 | |
| `RESOURCE_OPERATION_UPDATE_STATUS` | 4 | UPDATE\_STATUS is emitted only iff the resource's status has been updated. If the status and something else are updated, a single UPDATE event is emitted. |
| Value | Number | Description |
| -------------------------------------------- | -----: | ----------- |
| `RESOURCE_TYPE_UNSPECIFIED` | 0 | |
| `RESOURCE_TYPE_ENVIRONMENT` | 1 | |
| `RESOURCE_TYPE_RUNNER` | 2 | |
| `RESOURCE_TYPE_PROJECT` | 3 | |
| `RESOURCE_TYPE_TASK` | 4 | |
| `RESOURCE_TYPE_TASK_EXECUTION` | 5 | |
| `RESOURCE_TYPE_SERVICE` | 6 | |
| `RESOURCE_TYPE_ORGANIZATION` | 7 | |
| `RESOURCE_TYPE_USER` | 8 | |
| `RESOURCE_TYPE_ENVIRONMENT_CLASS` | 9 | |
| `RESOURCE_TYPE_RUNNER_SCM_INTEGRATION` | 10 | |
| `RESOURCE_TYPE_HOST_AUTHENTICATION_TOKEN` | 11 | |
| `RESOURCE_TYPE_GROUP` | 12 | |
| `RESOURCE_TYPE_PERSONAL_ACCESS_TOKEN` | 13 | |
| `RESOURCE_TYPE_USER_PREFERENCE` | 14 | |
| `RESOURCE_TYPE_SERVICE_ACCOUNT` | 15 | |
| `RESOURCE_TYPE_SECRET` | 16 | |
| `RESOURCE_TYPE_SSO_CONFIG` | 17 | |
| `RESOURCE_TYPE_DOMAIN_VERIFICATION` | 18 | |
| `RESOURCE_TYPE_AGENT_EXECUTION` | 19 | |
| `RESOURCE_TYPE_RUNNER_LLM_INTEGRATION` | 20 | |
| `RESOURCE_TYPE_AGENT` | 21 | |
| `RESOURCE_TYPE_ENVIRONMENT_SESSION` | 22 | |
| `RESOURCE_TYPE_USER_SECRET` | 23 | |
| `RESOURCE_TYPE_ORGANIZATION_POLICY` | 24 | |
| `RESOURCE_TYPE_ORGANIZATION_SECRET` | 25 | |
| `RESOURCE_TYPE_PROJECT_ENVIRONMENT_CLASS` | 26 | |
| `RESOURCE_TYPE_BILLING` | 27 | |
| `RESOURCE_TYPE_PROMPT` | 28 | |
| `RESOURCE_TYPE_COUPON` | 29 | |
| `RESOURCE_TYPE_COUPON_REDEMPTION` | 30 | |
| `RESOURCE_TYPE_ACCOUNT` | 31 | |
| `RESOURCE_TYPE_INTEGRATION` | 32 | |
| `RESOURCE_TYPE_WORKFLOW` | 33 | |
| `RESOURCE_TYPE_WORKFLOW_EXECUTION` | 34 | |
| `RESOURCE_TYPE_WORKFLOW_EXECUTION_ACTION` | 35 | |
| `RESOURCE_TYPE_SNAPSHOT` | 36 | |
| `RESOURCE_TYPE_PREBUILD` | 37 | |
| `RESOURCE_TYPE_ORGANIZATION_LLM_INTEGRATION` | 38 | |
| `RESOURCE_TYPE_CUSTOM_DOMAIN` | 39 | |
| `RESOURCE_TYPE_ROLE_ASSIGNMENT_CHANGED` | 40 | |
| `RESOURCE_TYPE_GROUP_MEMBERSHIP_CHANGED` | 41 | |
| `RESOURCE_TYPE_WEBHOOK` | 42 | |
| `RESOURCE_TYPE_SCIM_CONFIGURATION` | 43 | |
| `RESOURCE_TYPE_SERVICE_ACCOUNT_SECRET` | 44 | |
| `RESOURCE_TYPE_ANNOUNCEMENT_BANNER` | 45 | |
| `RESOURCE_TYPE_SERVICE_ACCOUNT_TOKEN` | 46 | |
| `RESOURCE_TYPE_ROLE_ASSIGNMENT` | 47 | |
| `RESOURCE_TYPE_WARM_POOL` | 48 | |
| `RESOURCE_TYPE_NOTIFICATION` | 49 | |
| `RESOURCE_TYPE_SECURITY_POLICY` | 50 | |