Markers API

Markers are little icons used in graphs to indicate a change. This can be a deploy using a "Deploy marker" or a custom event with a "Custom marker".

This Marker endpoint allows the creation and indexing of markers that are available per application.

Marker types

Deploy markers

Deploy markers are little dots at the bottom of each graph that indicate when a new revision of an application was deployed. They’re a great way to compare deploys with each another and see if the new version increased or decreased application performance.

A list of these markers is also shown on the "Deploys" page on AppSignal.com, in an Application context.

πŸ” For more information, also read our deploy markers page.

Custom markers

Custom markers provide a way to add more context to graphs, allowing you to add annotations yourself. Create a Custom marker for scaling operations, when there was a sudden spike in traffic or when a database was acting up.

πŸ” For more information, also read our custom markers page.

Marker create

This endpoint enables the creation of Deploy and Custom markers.

When creating the payload for this request you can select what type of marker to create by specifying the kind value.

Endpoint/api/[app_id]/markers.json
Request methodPOST
ContextApplications
Requires authentication?Yes
Response formatsJSON

Deploy marker

ParameterTypeDescription
kindStringThe kind of marker to be created - "deploy".
created_atDate - ISO 8601Time at which to insert the marker. Leave empty to use the current time.
repositoryStringGit link or reference, e.g. "main".
revisionStringGit revision reference. Used to create git diff links in the UI.
userStringUser that has initiated the deploy.

Payload example

{
  "marker": {
    "kind": "deploy",
    "created_at": "2015-07-21T15:06:31.737+02:00",
    "repository": "git@github.com:company/repository.git",
    "revision": "fe001015311af4769a4dad76bdbce4c8f5d022af",
    "user": "user"
  }
}

Payload example with curl

curl -H "Content-Type: application/json" -XPOST https://appsignal.com/api/[app-id]/markers.json?token=[your-personal-token] \
  -d '{ "marker":{ "kind": "deploy", "repository": "git@github.com:company/repository.git", "revision": "[revision]", "user": "[user]"}}'

All requests to AppSignal API endpoints require a personal API token given as an URL query parameter for authentication.

Custom marker

Used to annotate events that can impact your performance/error rate. Examples are: up/downscale of cloud infrastructure, maintenance on database, cause of error spikes.

ParameterTypeDescription
kindStringThe kind of marker to be created - "custom".
created_atDate - ISO 8601Time at which to insert the marker. Leave empty to use the current time.
iconString - OptionalEmoji to use for this Custom marker, defaults to πŸš€.
messageString - OptionalMessage shown when hovering over the marker in the UI. Truncated to 200 characters.

Payload example

{
  "marker": {
    "kind": "custom",
    "created_at": "2015-07-21T15:06:31.737+02:00",
    "icon": "πŸ’©",
    "message": "Accidentlly dropped production DB"
  }
}

Marker index

This endpoint returns a list of markers. Combines both Deploy and Custom markers.

Endpoint/api/[app_id]/markers.json
Request methodGET
ContextApplications
Requires authentication?Yes
Response formatsJSON

Parameters

ParameterTypeDescription
kindStringThe kind of marker to be created - "custom".
fromDate - ISO 8601 / Integer - UNIX timestampAll times are UTC.
toDate - ISO 8601 / Integer - UNIX timestampAll times are UTC.
limitIntegerLimit the number of markers returned.
count_onlyBooleanSet to "true" to only return the number of markers that exist.

Response

{
  "count": 4212,
  "markers": [
    {
      "kind": "deploy",
      "id": "50a61f1b660cd3677775ccb0",
      "created_at": "2015-07-21T15:06:31.737+02:00",
      "closed_at": null,
      "live_for": 107413,
      "live_for_in_words": "1d",
      "gem_version": null,
      "repository": "git@github.com:company/repository.git",
      "revision": "fe001015311af4769a4dad76bdbce4c8f5d022af",
      "short_revision": "fe00101",
      "git_compare_url": "https://github.com/company/repository/compare/aaa...bbb"
      "user": "user",
      "exception_count": 200,
      "exception_rate": 8.81
    },
    {
      "kind": "custom",
      "icon": "πŸ’©",
      "message": "Accidentlly dropped production DB",
      "created_at": "2015-07-21T15:06:31.737+02:00"
    },
    {
      "kind": "notification",
      "message": "Appsignal API issues.",
      "created_at": "2015-07-21T15:06:31.737+02:00"
    }
  ]
}

With "count_only": true.

{
  "count": 4212
}

Marker show

This endpoint returns the JSON representation of a single marker.

Endpoint/api/[app_id]/markers/[marker_id].json
Request methodGET
ContextApplications
Requires authentication?Yes
Response formatsJSON

Parameters

ParameterTypeDescription
marker_idStringThe id of the marker to return.

Response

The response for Deploy markers and Custom markers is different. Deploy markers contain more data about a certain deploy while Custom markers only contain the data given on creation.

Deploy marker

{
  "id": "50a61f1b660cd3677775ccb0",
  "created_at": "2015-07-21T15:06:31.737+02:00",
  "closed_at": null,
  "live_for": 107413,
  "live_for_in_words": "1d",
  "gem_version": null,
  "repository": "git@github.com:company/repository.git",
  "revision": "fe001015311af4769a4dad76bdbce4c8f5d022af",
  "short_revision": "fe00101",
  "git_compare_url": "https://github.com/company/repository/compare/aaa...bbb"
  "user": "user",
  "exception_count": 200,
  "exception_rate": 8.81
}

Custom marker

{
  "kind": "custom",
  "icon": "πŸ’©",
  "message": "Accidentlly dropped production DB",
  "created_at": "2015-07-21T15:06:31.737+02:00"
}

Notification marker

{
  "kind": "notification",
  "message": "Appsignal API issues.",
  "created_at": "2015-07-21T15:06:31.737+02:00"
}

Marker update

This endpoint updates a single marker and returns the JSON representation of the updated marker.

Endpoint/api/[app_id]/markers/[marker_id].json
Request methodPUT
ContextApplications
Requires authentication?Yes
Response formatsJSON

Parameters

ParameterTypeDescription
marker_idStringThe id of the marker to update.

Payload

The payload is the same as a create/POST request and differs per marker type.

Response

The response is the same as a show/GET request and differs per marker type.

Marker delete

This endpoint deletes a single marker.

Endpoint/api/[app_id]/markers/[marker_id].json
Request methodDELETE
ContextApplications
Requires authentication?Yes
Response formatsJSON

Parameters

ParameterTypeDescription
marker_idStringThe id of the marker to delete.

Response

The response body of this request is empty. The status code will return if it was successful or not.

Need more help?

Contact us and speak directly with the engineers working on AppSignal. They will help you get set up, tweak your code and make sure you get the most out of using AppSignal.

Contact us

Start a trial - 30 days free

AppSignal is a great way to monitor your Ruby, Elixir & Node.js applications. Works great with Rails, Phoenix, Express and other frameworks, with support for background jobs too. Let's improve your apps together.

Start a trial