> ## Documentation Index
> Fetch the complete documentation index at: https://moonshadow-ep3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

Events represent actions that occur in your connected integrations, such as a new GitHub pull request, a Slack message, or a Jira issue update. Use the Events API to query historical events or inspect a specific event in detail.

***

## List Events

Returns a paginated, filterable list of events for a workspace.

```bash theme={null}
curl -G https://api.moonshadow.dev/v1/workspaces/ws_abc123/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "type=pull_request" \
  -d "source=github" \
  -d "since=2024-06-01T00:00:00Z" \
  -d "limit=10"
```

### Path Parameters

<ParamField path="id" type="string" required>
  The workspace ID to query events for.
</ParamField>

### Query Parameters

<ParamField query="type" type="string">
  Filter by event type, e.g. `pull_request`, `message`, `issue`.
</ParamField>

<ParamField query="source" type="string">
  Filter by integration source, e.g. `github`, `slack`, `jira`.
</ParamField>

<ParamField query="since" type="string">
  ISO 8601 timestamp. Only return events created after this time.
</ParamField>

<ParamField query="limit" default="20" type="integer">
  Maximum number of events to return. Maximum is 100.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor from a previous response to fetch the next page.
</ParamField>

### Response

<ResponseField name="data" type="array">
  Array of event objects.
</ResponseField>

<ResponseField name="data[].event_id" type="string">
  Unique event identifier, e.g. `evt_mno345`.
</ResponseField>

<ResponseField name="data[].type" type="string">
  Event type, e.g. `pull_request`, `message`, `issue`.
</ResponseField>

<ResponseField name="data[].source" type="string">
  Integration source that fired the event.
</ResponseField>

<ResponseField name="data[].payload" type="object">
  Provider-specific event payload.
</ResponseField>

<ResponseField name="data[].created_at" type="string">
  ISO 8601 timestamp of when the event was received.
</ResponseField>

<ResponseField name="pagination" type="object">
  Cursor pagination metadata.
</ResponseField>

```json theme={null}
{
  "data": [
    {
      "event_id": "evt_mno345",
      "type": "pull_request",
      "source": "github",
      "payload": {
        "action": "opened",
        "number": 42,
        "repository": "acme/app",
        "title": "Add user authentication flow",
        "author": "alice"
      },
      "created_at": "2024-06-10T14:30:00Z"
    },
    {
      "event_id": "evt_pqr678",
      "type": "message",
      "source": "slack",
      "payload": {
        "channel": "#engineering",
        "user": "bob",
        "text": "Deployment to production is complete."
      },
      "created_at": "2024-06-10T14:25:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImV2dF9wcXI2NzgifQ==",
    "has_more": true
  }
}
```

***

## Get an Event

Retrieves a single event by its ID.

```bash theme={null}
curl https://api.moonshadow.dev/v1/workspaces/ws_abc123/events/evt_mno345 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Path Parameters

<ParamField path="id" type="string" required>
  The workspace ID.
</ParamField>

<ParamField path="eventId" type="string" required>
  The event ID to retrieve.
</ParamField>

### Response

```json theme={null}
{
  "event_id": "evt_mno345",
  "type": "pull_request",
  "source": "github",
  "payload": {
    "action": "opened",
    "number": 42,
    "repository": "acme/app",
    "title": "Add user authentication flow",
    "author": "alice",
    "url": "https://github.com/acme/app/pull/42"
  },
  "created_at": "2024-06-10T14:30:00Z"
}
```

## Event Object Shape

Every event shares the following fields:

<ResponseField name="event_id" type="string">
  Unique identifier for the event.
</ResponseField>

<ResponseField name="type" type="string">
  Category of the event. Common values: `pull_request`, `push`, `message`, `issue`, `commit`.
</ResponseField>

<ResponseField name="source" type="string">
  Name of the integration that produced the event.
</ResponseField>

<ResponseField name="payload" type="object">
  Raw data from the provider. The structure varies by `type` and `source`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when Moonshadow received the event.
</ResponseField>

## Filter Examples

<Accordion title="Filter by event type only">
  ```bash theme={null}
  curl -G https://api.moonshadow.dev/v1/workspaces/ws_abc123/events \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d "type=issue"
  ```
</Accordion>

<Accordion title="Filter by source and time range">
  ```bash theme={null}
  curl -G https://api.moonshadow.dev/v1/workspaces/ws_abc123/events \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d "source=slack" \
    -d "since=2024-06-08T00:00:00Z"
  ```
</Accordion>

<Accordion title="Fetch a large batch with pagination">
  ```bash theme={null}
  curl -G https://api.moonshadow.dev/v1/workspaces/ws_abc123/events \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d "limit=100"
  ```

  Then use the `next_cursor` from the response on subsequent requests:

  ```bash theme={null}
  curl -G https://api.moonshadow.dev/v1/workspaces/ws_abc123/events \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d "limit=100" \
    -d "cursor=eyJpZCI6ImV2dF9wcXI2NzgifQ=="
  ```
</Accordion>

## Filtering and Webhooks

For real-time event delivery, you can subscribe to webhooks instead of polling the Events API. See the [Webhooks Guide](/guides/webhooks) for setup instructions.