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

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

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

List Events

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

Path Parameters

string

required

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

Query Parameters

string

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

string

ISO 8601 start time to filter events from

string

ISO 8601 end time to filter events until

string

Filter to events that apply to a specific bucket

string

Filter to events that apply to a specific environment

number

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

Headers

string

required

Bearer token for authentication

Response

boolean

Indicates if there are more records to paginate through

array

Show Event Objects

string

Unique event identifier

string

Account identifier this event belongs to

string

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

string

Human-readable event name

string

Longer description of the event (nullable)

string

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

object

Freeform key/value metadata (nullable)

array

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

array

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

string

ISO 8601 timestamp when the event started

string

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

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"

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);

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)

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

string

required

Account identifier

string

required

Event identifier

Headers

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"

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);

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

string

required

Account identifier

Headers

string

required

Bearer token for authentication

Request Body

string

required

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

string

required

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

string

Longer description of the event

string

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

object

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

array

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

array

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

string

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

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

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);

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)

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

string

required

Account identifier

string

required

Event identifier

Headers

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

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);

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

string

required

Account identifier

string

required

Event identifier

Headers

string

required

Bearer token for authentication

Response

string

ID of the deleted event

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"

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);

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

​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