Events API

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

This page as Markdown

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 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 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 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.

bash

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'

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

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

bash

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

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

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

Response

The new event object.

bash

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

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

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

- 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

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

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. metadata is replaced as a whole, not merged.

Response

The updated event object.

bash

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

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

{
  "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 -X DELETE https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/events/evt_2kL4jH6gF8dS1aP3oI5uY7tR9eW \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"

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

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

Event markers: How markers appear on charts, and creating them in the app.
MCP tools: Let an AI assistant list and create events.

Events API

Event types and scope #

The event object #

List events #

Path parameters #

Query parameters #

Response #

Get event #

Path parameters #

Response #

Create event #

Path parameters #

Body parameters #

Response #

From your CI/CD pipeline #

Update event #

Path parameters #

Body parameters #

Response #

Delete event #

Path parameters #

Response #

Errors #

Related #

Event types and scope

The event object

List events

Path parameters

Query parameters

Response

Get event

Path parameters

Response

Create event

Path parameters

Body parameters

Response

From your CI/CD pipeline

Update event

Path parameters

Body parameters

Response

Delete event

Path parameters

Response

Errors

Related