Graphs API

Graphs are a way to group one or more metrics into a visual representation you can use to gain and share insights about your projects. Below we will walk through some examples that create and manipulate graphs that monitor the HTTP endpoints in question.

The USER_API_TOKEN used in the samples below can be found on your Settings page.

list

GET /api/2/organizations/:organization_id/projects/:project_id/graphs

Command Line Example

curl -H 'X-Instrumental-Token: USER_API_TOKEN' \
     https://instrumentalapp.com/api/2/organizations/1/projects/1/graphs

Example Response

HTTP Status: 200 OK
[
  {
    "continuous": false,
    "created_at": "2016-03-09T15:03:06.340Z",
    "dashboard_id": 2,
    "id": 2,
    "metrics": [
      "web.request.api.graphs.index.get"
    ],
    "position": 1,
    "project_id": 1,
    "stacked": false,
    "title": "API Graph Index Timing",
    "units": "ms",
    "updated_at": "2016-03-09T15:03:29.428Z",
    "description": null,
    "creator_id": null
  },
  {
    "continuous": false,
    "created_at": "2016-03-09T15:04:45.888Z",
    "dashboard_id": 2,
    "id": 3,
    "metrics": [
      "gauge_count(web.request.api.graphs.index.get)"
    ],
    "position": 2,
    "project_id": 1,
    "stacked": false,
    "title": "API Graph Index Request Count",
    "units": "requests",
    "updated_at": "2016-03-09T15:04:45.888Z",
    "description": "The count of requests made against the Graphs API",
    "creator_id": 1
  }
]

Example Response - authenticated User is not authorized to view Project

HTTP Status: 404 NOT FOUND

show

GET /api/2/organizations/:organization_id/projects/:project_id/graphs/:graph_id

Command Line Example

curl -H 'X-Instrumental-Token: USER_API_TOKEN' https://instrumentalapp.com/api/2/organizations/1/projects/1/graphs/4

Example Response

HTTP Status: 200 OK
{
  "continuous": false,
  "created_at": "2016-03-11T02:28:40.612Z",
  "dashboard_id": 2,
  "id": 4,
  "metrics": [
    "web.request.api.graphs.show.get"
  ],
  "position": 3,
  "project_id": 1,
  "stacked": false,
  "title": "API Graph Show Timing",
  "units": "ms",
  "updated_at": "2016-03-11T02:28:52.310Z",
  "description": null,
  "creator_id": null
}

Example Response - authenticated User is not authorized to view Project

HTTP Status: 404 NOT FOUND

create

POST /api/2/organizations/:organization_id/projects/:project_id/graphs/

Required Parameters

  • title string, limit 255 characters
  • dashboard_id integer, dashboard for this graph

Optional Parameters

  • description string, defaults to null, a place to describe any relevant non-obvious details of the graph
  • position integer, 0 or greater, position of graph in graph listing interface
  • units string, limit 255 characters, label for y axis
  • stacked boolean, defaults to false, enables visual stacking of each metric on the graph
  • continuous boolean, defaults to false,
  • metrics array of strings, list of metric expressions to show on graph; see Instrumental Query Language

Example Post Body

{
  "metrics": [
    "web.request.api.graphs.create.post"
  ],
  "title": "API Graph Create Timing",
  "description": "timing(ms) of requests to Api::GraphsController#create",
  "units": "ms"
}

Command Line Example

curl -H 'X-Instrumental-Token: USER_API_TOKEN' \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"title":"API Graph Create Timing","description": "timing(ms) of requests to Api::GraphsController#create","units":"ms","metrics":["web.request.api.graphs.create.post"]}' \
     https://instrumentalapp.com/api/2/organizations/1/projects/1/graphs

Example Response

HTTP Status: 201 CREATED
{
  "continuous": false,
  "created_at": "2016-03-11T04:11:59.924Z",
  "dashboard_id": 2,
  "id": 7,
  "metrics": [
    "web.request.api.graphs.create.post"
  ],
  "position": 6,
  "project_id": 1,
  "stacked": false,
  "title": "API Graph Create Timing",
  "units": "ms",
  "updated_at": "2016-03-11T04:11:59.924Z",
  "description": "timing(ms) of requests to Api::GraphsController#create",
  "creator_id": 1
}

Example Response - authenticated User is not authorized to edit Project

HTTP Status: 401 UNAUTHORIZED

Example Post Body - title too long

{
  title: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat duis aute irure dolor in reprehenderit.",
  metrics: [
    "jobs.success", "jobs.failure"
  ]
}

Example Response - title too long

HTTP Status: 422 UNPROCESSABLE ENTITY
["Title is too long (maximum is 255 characters)"]

update

PATCH /api/2/organizations/:organization_id/projects/:project_id/graphs/:graph_id

Optional Parameters

  • title string, limit 255 characters
  • description string, defaults to null, a place to describe any relevant non-obvious details of the graph
  • position integer, 0 or greater, position of graph in interface
  • units string, limit 255 characters, label for y axis
  • stacked boolean, defaults to false, enables visual stacking of each metric on the graph
  • continuous boolean, defaults to false,
  • dashboard_id integer, dashboard for this graph
  • metrics array of strings, list of metric expressions to show on graph; see Instrumental Query Language

Example Post Body

{ "units": "milliseconds" }

Command Line Example

curl -H 'X-Instrumental-Token: USER_API_TOKEN' \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d '{"units":"milliseconds"}' \
     https://instrumentalapp.com/api/2/organizations/1/projects/1/graphs/7

Example Response

HTTP Status: 204 NO CONTENT

Example Response - authenticated User is not authorized to edit Project

HTTP Status: 401 UNAUTHORIZED

Example Post Body - title too long

{
  title: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat duis aute irure dolor in reprehenderit.",
  metrics: ["jobs.success", "jobs.failure"]
}

Example Response - title too long

HTTP Status: 422 UNPROCESSABLE ENTITY
["Title is too long (maximum is 255 characters)"]

destroy

DELETE /api/2/organizations/:organization_id/projects/:project_id/graphs/:graph_id

Command Line Example

curl -H 'X-Instrumental-Token: USER_API_TOKEN' -X DELETE https://instrumentalapp.com/api/2/organizations/1/projects/1/graphs/6

Example Response

HTTP Status: 200 OK

Example Response - authenticated User is not authorized to edit Project

HTTP Status: 401 UNAUTHORIZED
Questions? We can help!