Metrics APIs

Table of Contents

The Metrics API allows site admins to get metrics metadata and metrics results to track activity on the platform. The Metrics APIs include endpoints for getting metrics metadata, such as what metrics exist for an app and the attributes on which those metrics can be queried. See the Metrics Documentation for more details.

See Instabase API authorization and response conventions for authorization and error convention details.

For the Metrics API, URL_BASE defines the base domain and API prefix of your Instabase instance.

For instabase.com, the URL_BASE is https://www.instabase.com/api/v1.
For an on-premises installation of Instabase, your URL_BASE will be different.

For all Metrics API calls, add ?pretty=true to the end of the query URL to return the JSON response in a more human readable, indented format.

Get apps

Method	Syntax
GET	`URL_BASE/metrics`

Description

Use this API to return a list apps that support metrics. Use the returned app name when making any subsequent metrics queries.

Request parameters

This API has no request parameters.

Response schema

The API returns a map of each app name to a structure of descriptors about that app.

Key	Description
`status`	Status indicating whether the API call succeeded. `OK` indicates success, `ERROR` indicates failure.
`data`	An object containing apps metadata. Present only if `status` is `OK`.
`data/apps`	An object containing app name/description pairs for all apps for which metrics are supported.

Examples

Request

url = URL_BASE + '/metrics'

payload = {}
headers = {
  'Authorization': f'Bearer {token}'
}

response = requests.get(url, headers=headers, data=payload)
resp_data = json.loads(response.content)

Response

HTTP STATUS CODE 200

# body
"status": "OK",
"data": {
    "apps": {
        "flow": {<description>},
        "ocr": {<description>},
        "diff": {<description>},
        "nlp": {<description>},
        "modelservice": {<description>},
        "modeltraining": {<description>},
        "refiner": {<description>},
        "reader": {<description>},
        "solution_builder": {<description>},
        "AIHub": {<description>}
    }
}

Get metrics

Method	Syntax
GET	`URL_BASE/metrics/<app-name>`

Description

Use this API to list all metrics that are supported for the specified app. Use the returned metric name when making any subsequent metrics queries.

Request parameters

This API has no request parameters.

Response schema

The API returns a map of each metric name to a structure of descriptors about that metric.

Key	Description
`status`	Status indicating whether the API call succeeded. `OK` indicates success, `ERROR` indicates failure.
`metrics`	An object containing metrics metadata. Present only if `status` is `OK`.
`data/metrics`	An array listing the metrics supported for the requested app.
`data/metrics/<metrics>`	An object containing metric name/description key/value pairs.

Examples

Request

url = URL_BASE + '/metrics/ocr'

payload = {}
headers = {
  'Authorization': f'Bearer {token}'
}

response = requests.get(url, headers=headers, data=payload)
resp_data = json.loads(response.content)

Response

HTTP STATUS CODE 200

# body
{
  "status": "OK",
  "data": {
    "metrics": [
      "num_calls": {<description>}
    ]
  }
}

Get attributes

Method	Syntax
GET	`URL_BASE/metrics/<app-name>/<metric-name>`

Description

Use this API to list all attributes that can used for filtering or aggregating on a metric query. Use the returned attribute name when making any subsequent metrics queries.

Request parameters

This API has no request parameters.

Response schema

The API returns a map of each attribute name to a structure of descriptors about that attribute.

Key	Description
`status`	Status indicating whether the API call succeeded. `OK` indicates success, `ERROR` indicates failure.
`data`	An object containing attributes metadata. Present only if `status` is `OK`.
`data/attributes`	An object defining the attributes supported for the requested metric.
`data/attributes/<attributes>`	An object containing attribute name/description key/value pairs.

Examples

Request

url = URL_BASE + '/metrics/ocr/num_calls'

payload = {}
headers = {
  'Authorization': f'Bearer {token}'
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
resp_data = json.loads(response.content)

Response

HTTP STATUS CODE 200

# body
"status": "OK",
"data": {
    "attributes": {
        "file_extension": {<description>},
        "ocr_model": {<description>},
        "repo": {<description>},
        "user": {<description>}
    }
}

Metrics query

Method	Syntax
POST	`URL_BASE/metrics/<app-name>/<metric-name>`

Description

Metrics query APIs.

Request parameters

Key	Type	Description	Value
`filter_by`	object	(Optional) Define metric attribute/value pairs on which to filter the results of the query.	An object containing metric attribute/value pairs, such as `"file_extension": "jpeg"`. See the Get attributes API response for the list of supported attribute names. Info Admin users can filter by `"username"` to view results from specific users only. Queries from non-admin users are automatically run only on metrics filtered by their own username.
`group_by`	string	(Optional) A metric attribute by which to group results.	A string specifying an attribute name. Use the Get attributes API response for a list of supported attribute names.
`group_by_time_interval`	string	A time interval by which to group results.	A string specifying a time interval. Valid values are `hour`, `day`, `week`, `month`, `quarter`, and `year`.
`start_time`	string	(Optional) The lower bound of the time range to restrict results. If a `start_time` is not provided, the default is one month before the `end_time`.	A string specifying a start time, in milliseconds since epoch.
`end_time`	string	(Optional) Upper bound on the time range to restrict results. If an `end_time` is not provided, the default is the current time.	A string specifying an end time, in milliseconds since epoch.

Response schema

Query results are returned as an array of results objects.

Key	Description
`status`	Status indicating whether the API call succeeded. `OK` indicates success, `ERROR` indicates failure.
`data`	An object containing attributes metadata. Present only if `status` is `OK`.
`data/results`	An array of objects containing metadata containing the results of the query.
`data/results/start_time`	Timestamp containing the starting time for the result.
`data/results/<attributes_value>`	(Optional) A string containing the value of the attribute by which the data was grouped. Present only if the request included a group by field.
`data/results/count`	Integer containing the count of the metric.

Examples

Requests

url = URL_BASE + '/metrics/ocr/num_calls'

payload = {
    "filter_by": {
        "file_extension": "jpeg"
    },
    "group_by": "repo",
    "group_by_time_interval": "week",
    "start_time": "1691499159000",
    "end_time": "1691519400000"
}

headers = {
  'Authorization': f'Bearer {token}'
}

response = requests.post(url, headers=headers, data=payload)
resp_data = json.loads(response.content)

Sample request for a count of all Solution Builder projects created under the username "lee":

Info

Filtering by username is available to admin users only.

url = URL_BASE + '/metrics/solution_builder/projects_created'

payload = {
    "filter_by": {
        "username": "lee",
    },
    "group_by_time_interval": "day",
    "start_time": "1690883070726",
    "end_time": "1691055870726"
}

headers = {
  'Authorization': f'Bearer {token}'
}

response = requests.post(url, headers=headers, data=payload)
resp_data = json.loads(response.content)

Response

HTTP STATUS CODE 200

# body
"status": "OK",
"data": {
    "results": [
        {
            "start_time": 1691366400000,
            "repo": "my-repo",
            "count": 80.0
        },
        {
            "start_time": 1691366400000,
            "repo": "demos-and-tests",
            "count": 35.0
        },
        {
            "start_time": 1691366400000,
            "repo": "new-repo",
            "count": 8.0
        }
    ]
}

HTTP STATUS CODE 200

# body
{
  "status": "OK",
  "data": {
    "results": [
      {
        "start_time": 1690848000000,
        "count": 1.0
      },
      {
        "flow_path": 1690934400000,
        "count": 0.0
      }
    ]
  }
}