Markers API - AppSignal Documentation

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 method	POST
Context	Applications
Requires authentication?	Yes
Response formats	JSON

Deploy marker

This method of reporting deploy markers is deprecated and may be removed at any time in the future.Set the revision config option instead, so AppSignal creates deploy markers from the version your application is running.Reporting deploy markers using this method is only useful for small applications that use one application instance. It creates a new deploy marker at a specific time, regardless of the version the application is actually running. This also means it’s more error prone to group data that shouldn’t belong to it under the deploy.

Parameter	Type	Description
kind	String	The kind of marker to be created - “deploy”.
created_at	Date - ISO 8601	Time at which to insert the marker. Leave empty to use the current time.
repository	String	Git link or reference, e.g. “main”.
revision	String	Git revision reference. Used to create git diff links in the UI.
user	String	User 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. If you want to create custom markers, but not use your Personal API token, you can use the public endpoint instead.

Parameter	Type	Description
kind	String	The kind of marker to be created - “custom”.
created_at	Date - ISO 8601	Time at which to insert the marker. Leave empty to use the current time.
icon	String - Optional	Emoji to use for this Custom marker, defaults to 🚀.
message	String - Optional	Message 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 method	`GET`
Context	Applications
Requires authentication?	Yes
Response formats	JSON

Parameters

Parameter	Type	Description
kind	String	The kind of marker to be created - “custom”.
from	Date - ISO 8601 / Integer - UNIX timestamp	All times are UTC.
to	Date - ISO 8601 / Integer - UNIX timestamp	All times are UTC.
limit	Integer	Limit the number of markers returned.
count_only	Boolean	Set 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 method	`GET`
Context	Applications
Requires authentication?	Yes
Response formats	JSON

Parameters

Parameter	Type	Description
marker_id	String	The 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 method	PUT
Context	Applications
Requires authentication?	Yes
Response formats	JSON

Parameters

Parameter	Type	Description
marker_id	String	The 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 method	DELETE
Context	Applications
Requires authentication?	Yes
Response formats	JSON

Parameters

Parameter	Type	Description
marker_id	String	The 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.

​Marker types

​Deploy markers

​Custom markers

​Marker create

​Deploy marker

​Payload example

​Payload example with curl

​Custom marker

​Payload example

​Marker index

​Parameters

​Response

​Marker show

​Parameters

​Response

​Deploy marker

​Custom marker

​Notification marker

​Marker update

​Parameters

​Payload

​Response

​Marker delete

​Parameters

​Response

Marker types

Deploy markers

Custom markers

Marker create

Deploy marker

Payload example

Payload example with curl

Custom marker

Payload example

Marker index

Parameters

Response

Marker show

Parameters

Response

Deploy marker

Custom marker

Notification marker

Marker update

Parameters

Payload

Response

Marker delete

Parameters

Response