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 charactersdashboard_id
integer, dashboard for this graph
Optional Parameters
description
string, defaults to null, a place to describe any relevant non-obvious details of the graphposition
integer, 0 or greater, position of graph in graph listing interfaceunits
string, limit 255 characters, label for y axisstacked
boolean, defaults to false, enables visual stacking of each metric on the graphcontinuous
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 charactersdescription
string, defaults to null, a place to describe any relevant non-obvious details of the graphposition
integer, 0 or greater, position of graph in interfaceunits
string, limit 255 characters, label for y axisstacked
boolean, defaults to false, enables visual stacking of each metric on the graphcontinuous
boolean, defaults to false,dashboard_id
integer, dashboard for this graphmetrics
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