# Events API

> Create, list, update and delete event markers (deploys, incidents, config changes) that appear on your ApiTraffic charts, typically from CI/CD.

Source: https://www.apitraffic.io/docs/api-reference/events

Events mark moments that matter (a deploy, an incident, a configuration change) on your dashboard and APM charts, so you can see whether error rates or latency moved right after one. Deploy events that carry a commit in `metadata` also let ApiTraffic link failing requests and slow spans to the code that was running. See [Events](https://www.apitraffic.io/docs/events) for how they appear in the app.

The most useful events are created automatically: add a step to your deploy pipeline that calls [Create event](#create-event) with a `user` API token.

**Plan:** creating and changing events needs a plan that includes **Deploy & incident markers**. Listing, reading and deleting existing events keep working if the plan changes. **Permissions:** any member, or a `user` or `administrator` API token.

## Event types and scope

`type` is free text (up to 100 characters). The app offers these, and gives each a colored badge in event lists (on charts, every marker uses the same color):

| `type` | Use it for |
| --- | --- |
| `deployment` | Releases, deploys and rollbacks |
| `incident` | Outages and degradations |
| `config_change` | Feature flags, settings and environment variable changes |
| `scale` | Scaling up or down |
| `custom` | Anything else |

Events of type `deployment`, `deploy` or `release` (and those the [Git integration](https://www.apitraffic.io/docs/git-integrations/overview) creates) are treated as deploys: AI fix prompts and code links look for the commit in their `metadata` (`commitSha`, `branch`, `repoFullName`).

An event applies to the buckets in `bucketSids` and the environments in `environmentSids`. `["*"]`, the default, means all of them.

## The event object

- **sid (string, required)**:
  The event's identifier (`evt_` followed by 27 letters and digits).

- **accountSid (string, required)**:
  The account.

- **type (string, required)**:
  The event type.

- **name (string, required)**:
  A short name shown on the chart, for example `deploy v2026.10.19`.

- **description (string | null)**:
  A longer description.

- **source (string | null)**:
  What created the event, for example `ci`, `github_actions` or `on-call`.

- **metadata (object | null)**:
  Your own key-value detail, for example `commitSha`, `branch`, `version` or `severity`.

- **bucketSids (string[], required)**:
  The buckets the event applies to, or `["*"]`.

- **environmentSids (string[], required)**:
  The environments the event applies to, or `["*"]`.

- **startedAt (string, required)**:
  When the event started (ISO 8601).

- **endedAt (string | null)**:
  When it ended. `null` for a moment in time, such as a deploy.

- **createdAt (string, required)**:
  When the event was recorded.

- **updatedAt (string | null)**:
  When it was last changed.

## List events

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/events`

Returns events, the most recent `startedAt` first. A filter on a bucket or environment also returns events that apply to all of them (`["*"]`).

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

### Query parameters

- **type (query, string)**:
  Only events of this type.

- **startTime (query, string)**:
  Only events that started at or after this time (ISO 8601).

- **endTime (query, string)**:
  Only events that started at or before this time (ISO 8601).

- **bucketSid (query, string)**:
  Only events that apply to this bucket.

- **environmentSid (query, string)**:
  Only events that apply to this environment.

- **limit (query, number, default 50)**:
  Most events to return, up to 100.

### Response

- **hasMore (boolean, required)**:
  Always `false`. To read further back, pass the `startedAt` of the oldest event you received as `endTime`.

- **records (object[], required)**:
  The events, as [event objects](#the-event-object).

```bash cURL
curl -G https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/events \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  --data-urlencode 'type=deployment' \
  --data-urlencode 'startTime=2026-10-13T00:00:00.000Z' \
  --data-urlencode 'limit=20'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const params = new URLSearchParams({ type: 'deployment', startTime: '2026-10-13T00:00:00.000Z', limit: '20' });
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/events?${params}`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { records } = await response.json();
```

```json 200
{
  "hasMore": false,
  "records": [
    {
      "sid": "evt_2tG5yH7uJ9iK1oL3pZ6xC8vB4nM",
      "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
      "bucketSids": ["*"],
      "environmentSids": ["prd7k2"],
      "type": "deployment",
      "name": "deploy v2026.10.19",
      "description": "Acme Store API v2026.10.19 rolled out to production.",
      "source": "ci",
      "metadata": {
        "service": "acme-store-api",
        "version": "v2026.10.19",
        "commitSha": "4e1b9c7a2d5f8e3b6a0c1d4f7e2a9b5c8d3e6f1a",
        "branch": "main"
      },
      "startedAt": "2026-10-19T10:00:00.000Z",
      "endedAt": null,
      "createdAt": "2026-10-19T10:00:02.000Z",
      "updatedAt": null
    }
  ]
}
```

## Get event

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/events/{eventSid}`

Returns one event.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **eventSid (path, string, required)**:
  The event's identifier (`evt_…`).

### Response

An [event object](#the-event-object).

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/events/evt_2tG5yH7uJ9iK1oL3pZ6xC8vB4nM \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const eventSid = 'evt_2tG5yH7uJ9iK1oL3pZ6xC8vB4nM';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/events/${eventSid}`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const event = await response.json();
```

```json 200
{
  "sid": "evt_2tG5yH7uJ9iK1oL3pZ6xC8vB4nM",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "bucketSids": ["*"],
  "environmentSids": ["prd7k2"],
  "type": "deployment",
  "name": "deploy v2026.10.19",
  "description": "Acme Store API v2026.10.19 rolled out to production.",
  "source": "ci",
  "metadata": {
    "service": "acme-store-api",
    "version": "v2026.10.19",
    "commitSha": "4e1b9c7a2d5f8e3b6a0c1d4f7e2a9b5c8d3e6f1a",
    "branch": "main"
  },
  "startedAt": "2026-10-19T10:00:00.000Z",
  "endedAt": null,
  "createdAt": "2026-10-19T10:00:02.000Z",
  "updatedAt": null
}
```

## Create event

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/events`

Records an event. It appears on charts straight away.

**Plan:** needs **Deploy & incident markers**.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

### Body parameters

- **type (body, string, required)**:
  The event type, up to 100 characters. See [Event types and scope](#event-types-and-scope).

- **name (body, string, required)**:
  A short name for the chart, up to 255 characters. Include a version or ticket number so it means something at a glance.

- **description (body, string | null)**:
  A longer description.

- **source (body, string | null)**:
  What created the event, up to 100 characters, for example `github_actions`.

- **metadata (body, object | null)**:
  Your own key-value detail. For deploys, include `commitSha` and `branch` (and `repoFullName` if you can) so failures can be traced to the commit.

- **bucketSids (body, string[], default ["*"])**:
  The buckets the event applies to.

- **environmentSids (body, string[], default ["*"])**:
  The environments the event applies to.

- **startedAt (body, string)**:
  When it started (ISO 8601). Defaults to now.

- **endedAt (body, string | null)**:
  When it ended. Leave it out for a moment in time; for an incident, set it later with [Update event](#update-event).

### Response

The new [event object](#the-event-object).

```bash cURL
curl -X POST https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/events \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "deployment",
    "name": "deploy v2026.10.20",
    "description": "Acme Store API v2026.10.20 rolled out to production.",
    "source": "ci",
    "metadata": {
      "service": "acme-store-api",
      "version": "v2026.10.20",
      "commitSha": "9d3c5a1e7b2f4d6a8c0e1b3d5f7a9c2e4b6d8f0a",
      "branch": "main"
    },
    "environmentSids": ["prd7k2"]
  }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/events`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'deployment',
    name: `deploy ${process.env.RELEASE_VERSION}`,
    source: 'ci',
    metadata: { commitSha: process.env.GIT_COMMIT, branch: 'main' },
    environmentSids: ['prd7k2'],
  }),
});
const event = await response.json();
```

```json 200
{
  "sid": "evt_2kL4jH6gF8dS1aP3oI5uY7tR9eW",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "bucketSids": ["*"],
  "environmentSids": ["prd7k2"],
  "type": "deployment",
  "name": "deploy v2026.10.20",
  "description": "Acme Store API v2026.10.20 rolled out to production.",
  "source": "ci",
  "metadata": {
    "service": "acme-store-api",
    "version": "v2026.10.20",
    "commitSha": "9d3c5a1e7b2f4d6a8c0e1b3d5f7a9c2e4b6d8f0a",
    "branch": "main"
  },
  "startedAt": "2026-10-20T10:00:00.000Z",
  "endedAt": null,
  "createdAt": "2026-10-20T10:00:00.000Z",
  "updatedAt": null
}
```

### From your CI/CD pipeline

Store your account sid and a `user` API token as pipeline secrets, then add a step after the deploy.

```yaml GitHub Actions
- name: Mark the deploy in ApiTraffic
  run: |
    curl -sf -X POST "https://api.apitraffic.io/v1/accounts/${{ secrets.APITRAFFIC_ACCOUNT_SID }}/events" \
      -H "Authorization: Bearer ${{ secrets.APITRAFFIC_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "deployment",
        "name": "deploy ${{ github.ref_name }}",
        "source": "github_actions",
        "metadata": {
          "commitSha": "${{ github.sha }}",
          "branch": "${{ github.ref_name }}",
          "repoFullName": "${{ github.repository }}",
          "runId": "${{ github.run_id }}"
        }
      }'
```

```yaml GitLab CI
mark_deploy:
  stage: deploy
  script:
    - |
      curl -sf -X POST "https://api.apitraffic.io/v1/accounts/${APITRAFFIC_ACCOUNT_SID}/events" \
        -H "Authorization: Bearer ${APITRAFFIC_TOKEN}" \
        -H "Content-Type: application/json" \
        -d "{
          \"type\": \"deployment\",
          \"name\": \"deploy ${CI_COMMIT_TAG:-$CI_COMMIT_SHORT_SHA}\",
          \"source\": \"gitlab_ci\",
          \"metadata\": {
            \"commitSha\": \"${CI_COMMIT_SHA}\",
            \"branch\": \"${CI_COMMIT_BRANCH}\",
            \"repoFullName\": \"${CI_PROJECT_PATH}\"
          }
        }"
```

```groovy Jenkins
post {
  success {
    sh """
      curl -sf -X POST "https://api.apitraffic.io/v1/accounts/\${APITRAFFIC_ACCOUNT_SID}/events" \\
        -H "Authorization: Bearer \${APITRAFFIC_TOKEN}" \\
        -H "Content-Type: application/json" \\
        -d '{
          "type": "deployment",
          "name": "deploy ${env.BUILD_TAG}",
          "source": "jenkins",
          "metadata": { "commitSha": "${env.GIT_COMMIT}", "buildNumber": "${env.BUILD_NUMBER}" }
        }'
    """
  }
}
```

> **Tip:** `curl -f` makes the step fail on an error response, so a wrong token shows up in the pipeline. If a missing marker should never block a release, add `|| true`.

## Update event

`PUT https://api.apitraffic.io/v1/accounts/{accountSid}/events/{eventSid}`

Changes an event. Send only the fields you want to change; the others keep their values. The usual case is closing an incident by setting `endedAt`.

**Plan:** needs **Deploy & incident markers**.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **eventSid (path, string, required)**:
  The event's identifier.

### Body parameters

Any of `type`, `name`, `description`, `source`, `metadata`, `bucketSids`, `environmentSids`, `startedAt` and `endedAt`, with the same rules as [Create event](#create-event). `metadata` is replaced as a whole, not merged.

### Response

The updated [event object](#the-event-object).

```bash cURL
curl -X PUT https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/events/evt_2pO4iU6yT8rE1wQ3aS5dF7gH9jZ \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "endedAt": "2026-10-19T14:40:00.000Z",
    "description": "The payments provider timed out under retry load. Recovered once it shed load; no captures lost."
  }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const eventSid = 'evt_2pO4iU6yT8rE1wQ3aS5dF7gH9jZ';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/events/${eventSid}`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ endedAt: '2026-10-19T14:40:00.000Z' }),
});
const event = await response.json();
```

```json 200
{
  "sid": "evt_2pO4iU6yT8rE1wQ3aS5dF7gH9jZ",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "bucketSids": ["*"],
  "environmentSids": ["prd7k2"],
  "type": "incident",
  "name": "INC-1019: payment capture failures",
  "description": "The payments provider timed out under retry load. Recovered once it shed load; no captures lost.",
  "source": "on-call",
  "metadata": { "severity": "SEV-2", "service": "payments", "status": "investigating" },
  "startedAt": "2026-10-19T14:00:00.000Z",
  "endedAt": "2026-10-19T14:40:00.000Z",
  "createdAt": "2026-10-19T14:03:10.000Z",
  "updatedAt": "2026-10-19T14:41:00.000Z"
}
```

## Delete event

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/events/{eventSid}`

Deletes an event. It disappears from charts and is no longer used for deploy correlation.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **eventSid (path, string, required)**:
  The event's identifier.

### Response

- **sid (string, required)**:
  The deleted event's identifier.

- **deleted (boolean, required)**:
  `true`.

```bash cURL
curl -X DELETE https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/events/evt_2kL4jH6gF8dS1aP3oI5uY7tR9eW \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const eventSid = 'evt_2kL4jH6gF8dS1aP3oI5uY7tR9eW';
await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/events/${eventSid}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
```

```json 200
{
  "sid": "evt_2kL4jH6gF8dS1aP3oI5uY7tR9eW",
  "deleted": true
}
```

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| `400` | `1000` | A field is missing or invalid, for example a `name` longer than 255 characters or a `startedAt` that is not a date. |
| `403` | `2221` | The plan does not include deploy and incident markers (create and update). |
| `404` | `4000` | No event with that `eventSid` in this account. |

## Related

- [Event markers](https://www.apitraffic.io/docs/events):
    How markers appear on charts, and creating them in the app.

- [MCP tools](https://www.apitraffic.io/docs/integrations/mcp-tools):
    Let an AI assistant list and create events.