> ## 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.
# Event Markers
> Correlate deployments, incidents, and infrastructure changes with your API traffic
## What Are Event Markers?
Event markers let you annotate your ApiTraffic dashboard with significant moments — deployments, incidents, configuration changes, scaling events — so you can visually correlate them with changes in your API's throughput, error rates, and response times.
When an event is created, it appears as a **vertical line on your Throughput and Response Time charts**, making it immediately obvious whether a deploy caused a latency spike or an incident coincided with a drop in traffic.
## Why Use Event Markers?
Without event markers, correlating API behavior changes with infrastructure events means switching between dashboards, CI/CD logs, and incident timelines. Event markers bring all of that context into one view:
* **Post-deploy verification** — Did error rates increase after the last release?
* **Incident correlation** — When did the degradation start relative to the config change?
* **Performance tracking** — Did the scaling event actually improve response times?
* **Team visibility** — Everyone on the team can see what changed and when, without digging through deploy logs.
## Event Types
| Type | When to use |
| --------------- | --------------------------------------------------------------- |
| `deployment` | Code releases, rollbacks, container image updates |
| `incident` | Outages, degradations, alerts firing |
| `config_change` | Feature flag toggles, environment variable updates, DNS changes |
| `scale` | Autoscaling events, manual instance scaling, database upgrades |
| `custom` | Anything else worth tracking |
## Creating Events
There are three ways to create events, depending on your workflow.
### From the Dashboard
Navigate to **Account → Events** in the left sidebar and click **Create Event**. This is useful for manually logging incidents or one-off events.
You can set:
* **Type** and **Name** (required)
* **Description** and **Source** (optional context)
* **Buckets** and **Environments** (scope the event or apply to all)
* **Started At** and **Ended At** (defaults to now if left blank)
### From Your CI/CD Pipeline
The most powerful use of events is **automated creation from your deployment pipeline**. By adding a single API call to the end of your deploy job, every release is automatically tracked on your charts.
You'll need:
1. Your **Account SID** (found in Account Settings)
2. An **API Token** (create one under Account → API Tokens)
Store both as secrets/environment variables in your CI/CD platform.
```yaml GitHub Actions theme={null}
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# ... your existing deploy steps ...
- name: Create ApiTraffic Deploy Event
if: success()
run: |
curl -s -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 }} @ ${{ github.sha }}",
"description": "Deployed by ${{ github.actor }}",
"source": "github_actions",
"metadata": {
"commitSha": "${{ github.sha }}",
"branch": "${{ github.ref_name }}",
"actor": "${{ github.actor }}",
"runId": "${{ github.run_id }}",
"runUrl": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
}
}'
```
```yaml GitLab CI theme={null}
deploy:
stage: deploy
script:
# ... your existing deploy steps ...
- |
curl -s -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} by ${GITLAB_USER_LOGIN}\",
\"source\": \"gitlab_ci\",
\"metadata\": {
\"commitSha\": \"${CI_COMMIT_SHA}\",
\"branch\": \"${CI_COMMIT_BRANCH}\",
\"pipelineId\": \"${CI_PIPELINE_ID}\",
\"pipelineUrl\": \"${CI_PIPELINE_URL}\"
}
}"
```
```groovy Jenkins (Jenkinsfile) theme={null}
pipeline {
agent any
stages {
stage('Deploy') {
steps {
// ... your existing deploy steps ...
}
}
}
post {
success {
sh """
curl -s -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}",
"description": "Build #${env.BUILD_NUMBER}",
"source": "jenkins",
"metadata": {
"buildNumber": "${env.BUILD_NUMBER}",
"jobName": "${env.JOB_NAME}",
"buildUrl": "${env.BUILD_URL}"
}
}'
"""
}
}
}
```
```yaml CircleCI theme={null}
version: 2.1
jobs:
deploy:
docker:
- image: cimg/base:stable
steps:
# ... your existing deploy steps ...
- run:
name: Create ApiTraffic Deploy Event
command: |
curl -s -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\": \"${CIRCLE_TAG:-$CIRCLE_SHA1}\",
\"description\": \"Job ${CIRCLE_JOB} on ${CIRCLE_BRANCH}\",
\"source\": \"circleci\",
\"metadata\": {
\"commitSha\": \"${CIRCLE_SHA1}\",
\"branch\": \"${CIRCLE_BRANCH}\",
\"buildUrl\": \"${CIRCLE_BUILD_URL}\"
}
}"
```
```bash Generic Script theme={null}
#!/bin/bash
# deploy-event.sh — call this at the end of any deploy script
ACCOUNT_SID="${APITRAFFIC_ACCOUNT_SID}"
API_TOKEN="${APITRAFFIC_API_TOKEN}"
EVENT_NAME="${1:-manual deploy}"
curl -s -X POST \
"https://api.apitraffic.io/v1/accounts/${ACCOUNT_SID}/events" \
-H "Authorization: Bearer ${API_TOKEN}" \
-H "Content-Type: application/json" \
-d "{
\"type\": \"deployment\",
\"name\": \"${EVENT_NAME}\",
\"source\": \"manual\",
\"metadata\": {
\"hostname\": \"$(hostname)\",
\"user\": \"$(whoami)\"
}
}"
```
### From an AI Assistant (MCP)
If you have an [MCP token](/api-reference/mcp-tokens) configured, AI assistants connected to ApiTraffic can create events using the `create_event` tool. This is useful for logging events conversationally:
> "Create a deployment event for v2.3.1 release on the production bucket"
The MCP server also exposes `list_events` for querying existing events.
## Scoping Events to Buckets & Environments
By default, events apply to **all buckets** and **all environments** (represented as `["*"]`). This means the event annotation will appear on every dashboard.
If your event only affects a specific service or environment, you can scope it:
```json theme={null}
{
"type": "deployment",
"name": "payments-service v1.4.2",
"bucketSids": ["bkt_abc123def456ghi789jkl012"],
"environmentSids": ["env_prod789uvw012rst345abc"]
}
```
Scoped events only appear on the matching bucket/environment dashboard, keeping charts clean and relevant.
When using the dashboard UI to create events, toggle off "Apply to all" under Buckets or Environments to select specific targets.
## The Metadata Field
The `metadata` field accepts any JSON object. Use it to store context that helps you trace from a chart annotation back to the exact change:
```json theme={null}
{
"metadata": {
"commitSha": "a1b2c3d4e5f6",
"branch": "main",
"imageTag": "v2.3.1",
"prNumber": 427,
"prUrl": "https://github.com/org/repo/pull/427",
"rollback": false
}
}
```
This data is stored with the event and returned in list/get API responses, making it available for auditing and automation.
## Point-in-Time vs Duration Events
**Point-in-time events** have only a `startedAt` timestamp (or leave it blank to default to "now"). These are ideal for deploys, config changes, and scaling events — things that happen at a specific moment.
**Duration events** have both `startedAt` and `endedAt` timestamps. These are ideal for incidents:
```json theme={null}
{
"type": "incident",
"name": "Database connection pool exhaustion",
"startedAt": "2024-01-15T14:00:00Z",
"endedAt": "2024-01-15T14:45:00Z"
}
```
You can create an incident event when it starts (without `endedAt`), then update it with the resolution time later using the [Update Event](/api-reference/events#update-event) API endpoint.
## Managing Events
Navigate to **Account → Events** in the dashboard to view, create, and delete events. The table shows:
* **Type** — color-coded badge
* **Name** — event title
* **Source** — where the event came from
* **Started At** — when it occurred
* **Actions** — delete events you no longer need
For programmatic management, see the full [Events API Reference](/api-reference/events).
## Best Practices
### Automate Everything
The most valuable events are the ones you don't have to remember to create. Add event creation to every deploy pipeline, every scaling automation, and every incident bot.
### Use Descriptive Names
Include version numbers, service names, or ticket IDs so events are meaningful at a glance on the chart:
* `payments-service v2.3.1`
* `feature-flag: dark-mode enabled`
* `INCIDENT-1234: API gateway timeout`
### Store Rich Metadata
Commit SHAs, PR links, Docker image tags, and pipeline URLs make it trivial to trace from a traffic anomaly to the exact change that caused it.
### Scope When Possible
If a deploy only touches one service, scope the event to that bucket. This keeps other dashboards uncluttered and makes the correlation signal stronger.
### Close Your Incidents
When an incident is resolved, update the event with `endedAt` and a resolution description. This creates a clear record of impact duration.
### Standardize Source Names
Pick consistent source identifiers across your team and pipelines:
| Source | Use for |
| ---------------- | ------------------------------------ |
| `github_actions` | GitHub Actions workflows |
| `gitlab_ci` | GitLab CI/CD pipelines |
| `jenkins` | Jenkins jobs |
| `circleci` | CircleCI workflows |
| `argocd` | Argo CD sync events |
| `manual` | Events created from the dashboard UI |
| `mcp` | Events created via AI assistant |
## What's Next?
Full CRUD API documentation with request/response examples
Connect AI assistants to create and query events