> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apitraffic.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Track deployments, incidents, and other markers to correlate with your API traffic

Events allow you to mark significant moments — deployments, incidents, configuration changes, scaling events — directly on your ApiTraffic dashboard charts. This makes it easy to correlate changes in error rates, latencies, and throughput with specific actions in your infrastructure.

## How Events Work

When you create an event, it appears as a vertical annotation on your Throughput and Response Time dashboard charts. This lets you visually answer questions like:

* "Did error rates spike after that deploy?"
* "Did response times improve after we scaled up?"
* "When exactly did that incident start?"

### Event Types

| Type            | Description                                 |
| --------------- | ------------------------------------------- |
| `deployment`    | Code releases, deploys, rollbacks           |
| `incident`      | Outages, degradations, alerts fired         |
| `config_change` | Feature flags, environment variable changes |
| `scale`         | Autoscaling events, manual scaling          |
| `custom`        | Anything else you want to track             |

### Scoping

Events can be scoped to specific **buckets** and/or **environments**, or applied globally:

* **`["*"]`** (default) — applies to all buckets or all environments
* **Specific SIDs** — e.g. `["bkt_abc123"]` to scope to a single bucket

Events scoped to a bucket will only appear on that bucket's dashboard. Events scoped to `["*"]` appear everywhere.

## Creating Events

There are three ways to create events:

### 1. Dashboard UI

Navigate to **Account → Events** and click **Create Event**. Fill in the type, name, description, and optionally scope to specific buckets and environments.

### 2. REST API

Send a `POST` request to create events programmatically — ideal for CI/CD pipelines.

### 3. MCP Server

If you have an MCP token configured, AI assistants can create events using the `create_event` tool.

***

## CI/CD Integration Examples

The most powerful use of events is automated creation from your CI/CD pipeline. Here are examples for common platforms:

<CodeGroup>
  ```yaml GitHub Actions theme={null}
  # Add to the end of your deploy job
  - name: Create ApiTraffic Deploy Event
    run: |
      curl -X POST "https://api.apitraffic.io/v1/accounts/${{ secrets.APITRAFFIC_ACCOUNT_SID }}/events" \
        -H "Authorization: Bearer ${{ secrets.APITRAFFIC_API_TOKEN }}" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "deployment",
          "name": "${{ github.ref_name }} deploy",
          "description": "Commit: ${{ github.sha }}",
          "source": "github_actions",
          "metadata": {
            "commitSha": "${{ github.sha }}",
            "branch": "${{ github.ref_name }}",
            "actor": "${{ github.actor }}",
            "runId": "${{ github.run_id }}"
          }
        }'
  ```

  ```yaml GitLab CI theme={null}
  # Add to your deploy stage
  create_event:
    stage: deploy
    script:
      - |
        curl -X POST "https://api.apitraffic.io/v1/accounts/${APITRAFFIC_ACCOUNT_SID}/events" \
          -H "Authorization: Bearer ${APITRAFFIC_API_TOKEN}" \
          -H "Content-Type: application/json" \
          -d "{
            \"type\": \"deployment\",
            \"name\": \"${CI_COMMIT_TAG:-$CI_COMMIT_SHORT_SHA} deploy\",
            \"description\": \"Pipeline: ${CI_PIPELINE_ID}\",
            \"source\": \"gitlab_ci\",
            \"metadata\": {
              \"commitSha\": \"${CI_COMMIT_SHA}\",
              \"branch\": \"${CI_COMMIT_BRANCH}\",
              \"pipelineId\": \"${CI_PIPELINE_ID}\"
            }
          }"
  ```

  ```groovy Jenkins theme={null}
  // Add to the end of your Jenkinsfile
  post {
      success {
          sh """
              curl -X POST "https://api.apitraffic.io/v1/accounts/\${APITRAFFIC_ACCOUNT_SID}/events" \
                -H "Authorization: Bearer \${APITRAFFIC_API_TOKEN}" \
                -H "Content-Type: application/json" \
                -d '{
                  "type": "deployment",
                  "name": "${env.BUILD_TAG} deploy",
                  "source": "jenkins",
                  "metadata": {
                    "buildNumber": "${env.BUILD_NUMBER}",
                    "jobName": "${env.JOB_NAME}"
                  }
                }'
          """
      }
  }
  ```
</CodeGroup>

***

## List Events

<api-endpoint method="GET" url="https://api.apitraffic.io/v1/accounts/{accountSid}/events" />

Retrieve events for an account, with optional filtering by type, time range, and bucket.

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier (format: `acc_` followed by 27 alphanumeric characters)
</ParamField>

### Query Parameters

<ParamField query="type" type="string">
  Filter by event type: `deployment`, `incident`, `config_change`, `scale`, `custom`
</ParamField>

<ParamField query="startTime" type="string">
  ISO 8601 start time to filter events from
</ParamField>

<ParamField query="endTime" type="string">
  ISO 8601 end time to filter events until
</ParamField>

<ParamField query="bucketSid" type="string">
  Filter to events that apply to a specific bucket
</ParamField>

<ParamField query="environmentSid" type="string">
  Filter to events that apply to a specific environment
</ParamField>

<ParamField query="limit" type="number">
  Maximum number of results (default: 25, max: 100)
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Response

<ResponseField name="hasMore" type="boolean">
  Indicates if there are more records to paginate through
</ResponseField>

<ResponseField name="records" type="array">
  <Expandable title="Event Objects">
    <ResponseField name="sid" type="string">
      Unique event identifier
    </ResponseField>

    <ResponseField name="accountSid" type="string">
      Account identifier this event belongs to
    </ResponseField>

    <ResponseField name="type" type="string">
      Event type: `deployment`, `incident`, `config_change`, `scale`, `custom`
    </ResponseField>

    <ResponseField name="name" type="string">
      Human-readable event name
    </ResponseField>

    <ResponseField name="description" type="string">
      Longer description of the event (nullable)
    </ResponseField>

    <ResponseField name="source" type="string">
      Source of the event, e.g. `github_actions`, `jenkins`, `manual` (nullable)
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Freeform key/value metadata (nullable)
    </ResponseField>

    <ResponseField name="bucketSids" type="array">
      Bucket SIDs this event applies to. `["*"]` means all buckets.
    </ResponseField>

    <ResponseField name="environmentSids" type="array">
      Environment SIDs this event applies to. `["*"]` means all environments.
    </ResponseField>

    <ResponseField name="startedAt" type="string">
      ISO 8601 timestamp when the event started
    </ResponseField>

    <ResponseField name="endedAt" type="string">
      ISO 8601 timestamp when the event ended (nullable for point-in-time events)
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of event creation
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events?type=deployment&limit=10" \
    -H "Authorization: Bearer your-jwt-token"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events?type=deployment&limit=10', {
    headers: {
      'Authorization': 'Bearer your-jwt-token'
    }
  });

  const events = await response.json();
  console.log(events);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events',
      headers={'Authorization': 'Bearer your-jwt-token'},
      params={'type': 'deployment', 'limit': 10}
  )

  events = response.json()
  print(events)
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "hasMore": false,
    "records": [
      {
        "sid": "evt_abc123def456ghi789jkl012",
        "accountSid": "acc_abc123def456ghi789jkl012",
        "type": "deployment",
        "name": "v2.3.1 production release",
        "description": "Commit: a1b2c3d4",
        "source": "github_actions",
        "metadata": {
          "commitSha": "a1b2c3d4e5f6",
          "branch": "main",
          "actor": "jsmith"
        },
        "bucketSids": ["*"],
        "environmentSids": ["*"],
        "startedAt": "2024-01-15T14:30:00.000Z",
        "endedAt": null,
        "createdAt": "2024-01-15T14:30:05.000Z"
      }
    ]
  }
  ```
</ResponseExample>

***

## Get Event

<api-endpoint method="GET" url="https://api.apitraffic.io/v1/accounts/{accountSid}/events/{eventSid}" />

Retrieve details of a specific event.

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier
</ParamField>

<ParamField path="eventSid" type="string" required>
  Event identifier
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Response

Returns a single event object with the same structure as described in the List Events response.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events/evt_abc123def456ghi789jkl012" \
    -H "Authorization: Bearer your-jwt-token"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events/evt_abc123def456ghi789jkl012', {
    headers: {
      'Authorization': 'Bearer your-jwt-token'
    }
  });

  const event = await response.json();
  console.log(event);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "sid": "evt_abc123def456ghi789jkl012",
    "accountSid": "acc_abc123def456ghi789jkl012",
    "type": "deployment",
    "name": "v2.3.1 production release",
    "description": "Commit: a1b2c3d4",
    "source": "github_actions",
    "metadata": {
      "commitSha": "a1b2c3d4e5f6",
      "branch": "main"
    },
    "bucketSids": ["*"],
    "environmentSids": ["*"],
    "startedAt": "2024-01-15T14:30:00.000Z",
    "endedAt": null,
    "createdAt": "2024-01-15T14:30:05.000Z"
  }
  ```
</ResponseExample>

***

## Create Event

<api-endpoint method="POST" url="https://api.apitraffic.io/v1/accounts/{accountSid}/events" />

Create a new event marker.

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Request Body

<ParamField body="type" type="string" required>
  Event type: `deployment`, `incident`, `config_change`, `scale`, `custom`
</ParamField>

<ParamField body="name" type="string" required>
  Human-readable event name (e.g. "v2.3.1 production release")
</ParamField>

<ParamField body="description" type="string">
  Longer description of the event
</ParamField>

<ParamField body="source" type="string">
  Source of the event (e.g. `github_actions`, `gitlab_ci`, `jenkins`, `manual`)
</ParamField>

<ParamField body="metadata" type="object">
  Freeform key/value metadata. Use this to store commit SHAs, branch names, image tags, or any other context.
</ParamField>

<ParamField body="bucketSids" type="array">
  Bucket SIDs this event applies to. Defaults to `["*"]` (all buckets).
</ParamField>

<ParamField body="environmentSids" type="array">
  Environment SIDs this event applies to. Defaults to `["*"]` (all environments).
</ParamField>

<ParamField body="startedAt" type="string">
  ISO 8601 timestamp when the event started. Defaults to the current time.
</ParamField>

<ParamField body="endedAt" type="string">
  ISO 8601 timestamp when the event ended. Leave null for point-in-time events (e.g. a deploy).
</ParamField>

### Response

Returns the created event object.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events" \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "deployment",
      "name": "v2.3.1 production release",
      "description": "Deployed from main branch",
      "source": "github_actions",
      "metadata": {
        "commitSha": "a1b2c3d4e5f6",
        "branch": "main",
        "imageTag": "v2.3.1"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-jwt-token',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'deployment',
      name: 'v2.3.1 production release',
      description: 'Deployed from main branch',
      source: 'github_actions',
      metadata: {
        commitSha: 'a1b2c3d4e5f6',
        branch: 'main',
        imageTag: 'v2.3.1'
      }
    })
  });

  const event = await response.json();
  console.log(event);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events',
      headers={
          'Authorization': 'Bearer your-jwt-token',
          'Content-Type': 'application/json'
      },
      json={
          'type': 'deployment',
          'name': 'v2.3.1 production release',
          'description': 'Deployed from main branch',
          'source': 'github_actions',
          'metadata': {
              'commitSha': 'a1b2c3d4e5f6',
              'branch': 'main',
              'imageTag': 'v2.3.1'
          }
      }
  )

  event = response.json()
  print(event)
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "sid": "evt_new789uvw012rst345def",
    "accountSid": "acc_abc123def456ghi789jkl012",
    "type": "deployment",
    "name": "v2.3.1 production release",
    "description": "Deployed from main branch",
    "source": "github_actions",
    "metadata": {
      "commitSha": "a1b2c3d4e5f6",
      "branch": "main",
      "imageTag": "v2.3.1"
    },
    "bucketSids": ["*"],
    "environmentSids": ["*"],
    "startedAt": "2024-01-15T14:30:00.000Z",
    "endedAt": null,
    "createdAt": "2024-01-15T14:30:05.000Z"
  }
  ```
</ResponseExample>

***

## Update Event

<api-endpoint method="PUT" url="https://api.apitraffic.io/v1/accounts/{accountSid}/events/{eventSid}" />

Update an existing event. Useful for setting the `endedAt` time on an incident or updating metadata.

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier
</ParamField>

<ParamField path="eventSid" type="string" required>
  Event identifier
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Request Body

All fields from the Create Event request body are accepted. Only provided fields will be updated.

### Response

Returns the updated event object.

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events/evt_abc123def456ghi789jkl012" \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
      "endedAt": "2024-01-15T15:00:00.000Z",
      "description": "Incident resolved - root cause was database connection pool exhaustion"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events/evt_abc123def456ghi789jkl012', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer your-jwt-token',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      endedAt: '2024-01-15T15:00:00.000Z',
      description: 'Incident resolved - root cause was database connection pool exhaustion'
    })
  });

  const event = await response.json();
  console.log(event);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "sid": "evt_abc123def456ghi789jkl012",
    "accountSid": "acc_abc123def456ghi789jkl012",
    "type": "incident",
    "name": "Database connection spike",
    "description": "Incident resolved - root cause was database connection pool exhaustion",
    "source": "manual",
    "metadata": null,
    "bucketSids": ["*"],
    "environmentSids": ["*"],
    "startedAt": "2024-01-15T14:00:00.000Z",
    "endedAt": "2024-01-15T15:00:00.000Z",
    "createdAt": "2024-01-15T14:05:00.000Z"
  }
  ```
</ResponseExample>

***

## Delete Event

<api-endpoint method="DELETE" url="https://api.apitraffic.io/v1/accounts/{accountSid}/events/{eventSid}" />

Delete an event marker.

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier
</ParamField>

<ParamField path="eventSid" type="string" required>
  Event identifier
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Response

<ResponseField name="sid" type="string">
  ID of the deleted event
</ResponseField>

<ResponseField name="deleted" type="boolean">
  Flag indicating the event was successfully deleted
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events/evt_abc123def456ghi789jkl012" \
    -H "Authorization: Bearer your-jwt-token"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events/evt_abc123def456ghi789jkl012', {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer your-jwt-token'
    }
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "sid": "evt_abc123def456ghi789jkl012",
    "deleted": true
  }
  ```
</ResponseExample>

***

## MCP Server Access

Events are also accessible through the ApiTraffic MCP server, allowing AI assistants to create and list events:

| Tool           | Description                                                       |
| -------------- | ----------------------------------------------------------------- |
| `list_events`  | List event markers with filtering by type, time range, and bucket |
| `create_event` | Create a new event marker                                         |

To use MCP tools, you need an MCP token configured in your account. See [MCP Tokens](/api-reference/mcp-tokens) for setup instructions.

## Best Practices

<Tip>
  **Automate event creation** — The most valuable events are created automatically by your CI/CD pipeline. Add a deploy event step to every release workflow so you never miss a correlation.
</Tip>

* **Use descriptive names** — Include version numbers, branch names, or ticket IDs in event names so they're meaningful at a glance on the chart.
* **Add metadata** — Store commit SHAs, Docker image tags, PR numbers, and other context in the `metadata` field. This makes it easy to trace back from a traffic anomaly to the exact change.
* **Scope when possible** — If a deploy only affects one service/bucket, scope the event to that bucket. This keeps dashboards clean and focused.
* **Close incidents** — When an incident is resolved, update the event with an `endedAt` timestamp and a description of the resolution.
* **Use consistent sources** — Standardize on source names like `github_actions`, `gitlab_ci`, `jenkins`, `manual` across your team.