Events

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:

# 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 }}"
        }
      }'

List Events

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

Path Parameters

accountSid

string

required

Account identifier (format: acc_ followed by 27 alphanumeric characters)

Query Parameters

type

string

Filter by event type: deployment, incident, config_change, scale, custom

startTime

string

ISO 8601 start time to filter events from

endTime

string

ISO 8601 end time to filter events until

bucketSid

string

Filter to events that apply to a specific bucket

environmentSid

string

Filter to events that apply to a specific environment

limit

number

Maximum number of results (default: 25, max: 100)

Headers

Authorization

string

required

Bearer token for authentication

Response

hasMore

boolean

Indicates if there are more records to paginate through

records

array

Show Event Objects

sid

string

Unique event identifier

accountSid

string

Account identifier this event belongs to

type

string

Event type: deployment, incident, config_change, scale, custom

name

string

Human-readable event name

description

string

Longer description of the event (nullable)

source

string

Source of the event, e.g. github_actions, jenkins, manual (nullable)

metadata

object

Freeform key/value metadata (nullable)

bucketSids

array

Bucket SIDs this event applies to. ["*"] means all buckets.

environmentSids

array

Environment SIDs this event applies to. ["*"] means all environments.

startedAt

string

ISO 8601 timestamp when the event started

endedAt

string

ISO 8601 timestamp when the event ended (nullable for point-in-time events)

createdAt

string

ISO 8601 timestamp of event creation

curl -X GET "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events?type=deployment&limit=10" \
  -H "Authorization: Bearer your-jwt-token"

{
  "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"
    }
  ]
}

Get Event

Retrieve details of a specific event.

Path Parameters

accountSid

string

required

Account identifier

eventSid

string

required

Event identifier

Headers

Authorization

string

required

Bearer token for authentication

Response

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

curl -X GET "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events/evt_abc123def456ghi789jkl012" \
  -H "Authorization: Bearer your-jwt-token"

{
  "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"
}

Create Event

Create a new event marker.

Path Parameters

accountSid

string

required

Account identifier

Headers

Authorization

string

required

Bearer token for authentication

Request Body

type

string

required

Event type: deployment, incident, config_change, scale, custom

name

string

required

Human-readable event name (e.g. “v2.3.1 production release”)

description

string

Longer description of the event

source

string

Source of the event (e.g. github_actions, gitlab_ci, jenkins, manual)

metadata

object

Freeform key/value metadata. Use this to store commit SHAs, branch names, image tags, or any other context.

bucketSids

array

Bucket SIDs this event applies to. Defaults to ["*"] (all buckets).

environmentSids

array

Environment SIDs this event applies to. Defaults to ["*"] (all environments).

startedAt

string

ISO 8601 timestamp when the event started. Defaults to the current time.

endedAt

string

ISO 8601 timestamp when the event ended. Leave null for point-in-time events (e.g. a deploy).

Response

Returns the created event object.

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"
    }
  }'

{
  "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"
}

Update Event

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

Path Parameters

accountSid

string

required

Account identifier

eventSid

string

required

Event identifier

Headers

Authorization

string

required

Bearer token for authentication

Request Body

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

Response

Returns the updated event object.

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"
  }'

{
  "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"
}

Delete Event

Delete an event marker.

Path Parameters

accountSid

string

required

Account identifier

eventSid

string

required

Event identifier

Headers

Authorization

string

required

Bearer token for authentication

Response

sid

string

ID of the deleted event

deleted

boolean

Flag indicating the event was successfully deleted

curl -X DELETE "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/events/evt_abc123def456ghi789jkl012" \
  -H "Authorization: Bearer your-jwt-token"

{
  "sid": "evt_abc123def456ghi789jkl012",
  "deleted": true
}

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 for setup instructions.

Best Practices

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.

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.

API Documentation

Core Resources

Data Management

Automation

How Events Work

Event Types

Scoping

Creating Events

1. Dashboard UI

2. REST API

3. MCP Server

CI/CD Integration Examples

List Events

Path Parameters

Query Parameters

Headers

Response

Get Event

Path Parameters

Headers

Response

Create Event

Path Parameters

Headers

Request Body

Response

Update Event

Path Parameters

Headers

Request Body

Response

Delete Event

Path Parameters

Headers

Response

MCP Server Access

Best Practices

API Documentation

Core Resources

Data Management

Automation

​How Events Work

​Event Types

​Scoping

​Creating Events

​1. Dashboard UI

​2. REST API

​3. MCP Server

​CI/CD Integration Examples

​List Events

​Path Parameters

​Query Parameters

​Headers

​Response

​Get Event

​Path Parameters

​Headers

​Response

​Create Event

​Path Parameters

​Headers

​Request Body

​Response

​Update Event

​Path Parameters

​Headers

​Request Body

​Response

​Delete Event

​Path Parameters

​Headers

​Response

​MCP Server Access

​Best Practices

How Events Work

Event Types

Scoping

Creating Events

1. Dashboard UI

2. REST API

3. MCP Server

CI/CD Integration Examples

List Events

Path Parameters

Query Parameters

Headers

Response

Get Event

Path Parameters

Headers

Response

Create Event

Path Parameters

Headers

Request Body

Response

Update Event

Path Parameters

Headers

Request Body

Response

Delete Event

Path Parameters

Headers

Response

MCP Server Access

Best Practices