REST API endpoints for API Insights - Enterprise Cloud Docs

Get API request count statistics for an actor broken down by route within a specified time frame.

Fine-grained access tokens for "Get route stats by actor"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"API Insights" organization permissions (read)

Parameters for "Get route stats by actor"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`actor_type` string Required The type of the actor Can be one of: `installation`, `classic_pat`, `fine_grained_pat`, `oauth_app`, `_app_user_to_server`
`actor_id` integer Required The ID of the actor

Query parameters
Name, Type, Description
`min_timestamp` string Required The minimum timestamp to query for stats. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`max_timestamp` string The maximum timestamp to query for stats. Defaults to the time 30 days ago. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`direction` string The direction to sort the results by. Default: `desc` Can be one of: `asc`, `desc`
`sort` array The property to sort the results by.
`api_route_substring` string Providing a substring will filter results where the API route contains the substring. This is a case-insensitive search.

HTTP response status codes for "Get route stats by actor"

Status code	Description
`200`	OK

Code samples for "Get route stats by actor"

If you access at GHE.com, replace api..com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/insights/api/route-stats/{actor_type}/{actor_id}

curl -L \ -H "Accept: application/vnd.+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X--Api-Version: 2022-11-28" \ "https://api..com/orgs/ORG/insights/api/route-stats/ACTOR_TYPE/ACTOR_ID?min_timestamp=MIN_TIMESTAMP"

Response

Status: 200

[ { "http_method": "GET", "api_route": "/repositories/:repository_id", "total_request_count": 544665, "rate_limited_request_count": 13, "last_request_timestamp": "2024-09-18T15:43:03Z", "last_rate_limited_timestamp": "2024-09-18T06:30:09Z" } ]

Get API request statistics for all subjects within an organization within a specified time frame. Subjects can be users or Apps.

Fine-grained access tokens for "Get subject stats"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"API Insights" organization permissions (read)

Parameters for "Get subject stats"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

Query parameters
Name, Type, Description
`min_timestamp` string Required The minimum timestamp to query for stats. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`max_timestamp` string The maximum timestamp to query for stats. Defaults to the time 30 days ago. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`direction` string The direction to sort the results by. Default: `desc` Can be one of: `asc`, `desc`
`sort` array The property to sort the results by.
`subject_name_substring` string Providing a substring will filter results where the subject name contains the substring. This is a case-insensitive search.

HTTP response status codes for "Get subject stats"

Status code	Description
`200`	OK

Code samples for "Get subject stats"

If you access at GHE.com, replace api..com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/insights/api/subject-stats

curl -L \ -H "Accept: application/vnd.+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X--Api-Version: 2022-11-28" \ "https://api..com/orgs/ORG/insights/api/subject-stats?min_timestamp=MIN_TIMESTAMP"

Response

Status: 200

[ { "subject_type": "installation", "subject_id": 954453, "subject_name": " Actions", "integration_id": 124345, "total_request_count": 544665, "rate_limited_request_count": 13, "last_request_timestamp": "2024-09-18T15:43:03Z", "last_rate_limited_timestamp": "2024-09-18T06:30:09Z" } ]

Get overall statistics of API requests made within an organization by all users and apps within a specified time frame.

Fine-grained access tokens for "Get summary stats"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"API Insights" organization permissions (read)

Parameters for "Get summary stats"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

Query parameters
Name, Type, Description
`min_timestamp` string Required The minimum timestamp to query for stats. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`max_timestamp` string The maximum timestamp to query for stats. Defaults to the time 30 days ago. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.

HTTP response status codes for "Get summary stats"

Status code	Description
`200`	OK

Code samples for "Get summary stats"

If you access at GHE.com, replace api..com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/insights/api/summary-stats

curl -L \ -H "Accept: application/vnd.+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X--Api-Version: 2022-11-28" \ "https://api..com/orgs/ORG/insights/api/summary-stats?min_timestamp=MIN_TIMESTAMP"

Response

Status: 200

{ "total_request_count": 34225, "rate_limited_request_count": 23 }

Get overall statistics of API requests within the organization for a user.

Fine-grained access tokens for "Get summary stats by user"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"API Insights" organization permissions (read)

Parameters for "Get summary stats by user"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`user_id` string Required The ID of the user to query for stats

Query parameters
Name, Type, Description
`min_timestamp` string Required The minimum timestamp to query for stats. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`max_timestamp` string The maximum timestamp to query for stats. Defaults to the time 30 days ago. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.

HTTP response status codes for "Get summary stats by user"

Status code	Description
`200`	OK

Code samples for "Get summary stats by user"

If you access at GHE.com, replace api..com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/insights/api/summary-stats/users/{user_id}

curl -L \ -H "Accept: application/vnd.+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X--Api-Version: 2022-11-28" \ "https://api..com/orgs/ORG/insights/api/summary-stats/users/USER_ID?min_timestamp=MIN_TIMESTAMP"

Response

Status: 200

{ "total_request_count": 34225, "rate_limited_request_count": 23 }

Get overall statistics of API requests within the organization made by a specific actor. Actors can be App installations, OAuth apps or other tokens on behalf of a user.

Fine-grained access tokens for "Get summary stats by actor"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"API Insights" organization permissions (read)

Parameters for "Get summary stats by actor"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`actor_type` string Required The type of the actor Can be one of: `installation`, `classic_pat`, `fine_grained_pat`, `oauth_app`, `_app_user_to_server`
`actor_id` integer Required The ID of the actor

Query parameters
Name, Type, Description
`min_timestamp` string Required The minimum timestamp to query for stats. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`max_timestamp` string The maximum timestamp to query for stats. Defaults to the time 30 days ago. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.

HTTP response status codes for "Get summary stats by actor"

Status code	Description
`200`	OK

Code samples for "Get summary stats by actor"

If you access at GHE.com, replace api..com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/insights/api/summary-stats/{actor_type}/{actor_id}

curl -L \ -H "Accept: application/vnd.+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X--Api-Version: 2022-11-28" \ "https://api..com/orgs/ORG/insights/api/summary-stats/ACTOR_TYPE/ACTOR_ID?min_timestamp=MIN_TIMESTAMP"

Response

Status: 200

{ "total_request_count": 34225, "rate_limited_request_count": 23 }

Get the number of API requests and rate-limited requests made within an organization over a specified time period.

Fine-grained access tokens for "Get time stats"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"API Insights" organization permissions (read)

Parameters for "Get time stats"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

Query parameters
Name, Type, Description
`min_timestamp` string Required The minimum timestamp to query for stats. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`max_timestamp` string The maximum timestamp to query for stats. Defaults to the time 30 days ago. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`timestamp_increment` string Required The increment of time used to breakdown the query results (5m, 10m, 1h, etc.)

HTTP response status codes for "Get time stats"

Status code	Description
`200`	OK

Code samples for "Get time stats"

If you access at GHE.com, replace api..com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/insights/api/time-stats

curl -L \ -H "Accept: application/vnd.+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X--Api-Version: 2022-11-28" \ "https://api..com/orgs/ORG/insights/api/time-stats?min_timestamp=MIN_TIMESTAMP&timestamp_increment=TIMESTAMP_INCREMENT"

Response

Status: 200

[ { "timestamp": "2024-09-11T15:00:00Z", "total_request_count": 34225, "rate_limited_request_count": 0 }, { "timestamp": "2024-09-11T15:05:00Z", "total_request_count": 10587, "rate_limited_request_count": 18 }, { "timestamp": "2024-09-11T15:10:00Z", "total_request_count": 43587, "rate_limited_request_count": 14 }, { "timestamp": "2024-09-11T15:15:00Z", "total_request_count": 19463, "rate_limited_request_count": 4 }, { "timestamp": "2024-09-11T15:20:00Z", "total_request_count": 60542, "rate_limited_request_count": 3 }, { "timestamp": "2024-09-11T15:25:00Z", "total_request_count": 55872, "rate_limited_request_count": 23 } ]

Get the number of API requests and rate-limited requests made within an organization by a specific user over a specified time period.

Fine-grained access tokens for "Get time stats by user"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"API Insights" organization permissions (read)

Parameters for "Get time stats by user"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`user_id` string Required The ID of the user to query for stats

Query parameters
Name, Type, Description
`min_timestamp` string Required The minimum timestamp to query for stats. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`max_timestamp` string The maximum timestamp to query for stats. Defaults to the time 30 days ago. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`timestamp_increment` string Required The increment of time used to breakdown the query results (5m, 10m, 1h, etc.)

HTTP response status codes for "Get time stats by user"

Status code	Description
`200`	OK

Code samples for "Get time stats by user"

If you access at GHE.com, replace api..com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/insights/api/time-stats/users/{user_id}

curl -L \ -H "Accept: application/vnd.+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X--Api-Version: 2022-11-28" \ "https://api..com/orgs/ORG/insights/api/time-stats/users/USER_ID?min_timestamp=MIN_TIMESTAMP&timestamp_increment=TIMESTAMP_INCREMENT"

Response

Status: 200

[ { "timestamp": "2024-09-11T15:00:00Z", "total_request_count": 34225, "rate_limited_request_count": 0 }, { "timestamp": "2024-09-11T15:05:00Z", "total_request_count": 10587, "rate_limited_request_count": 18 }, { "timestamp": "2024-09-11T15:10:00Z", "total_request_count": 43587, "rate_limited_request_count": 14 }, { "timestamp": "2024-09-11T15:15:00Z", "total_request_count": 19463, "rate_limited_request_count": 4 }, { "timestamp": "2024-09-11T15:20:00Z", "total_request_count": 60542, "rate_limited_request_count": 3 }, { "timestamp": "2024-09-11T15:25:00Z", "total_request_count": 55872, "rate_limited_request_count": 23 } ]

Get the number of API requests and rate-limited requests made within an organization by a specific actor within a specified time period.

Fine-grained access tokens for "Get time stats by actor"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"API Insights" organization permissions (read)

Parameters for "Get time stats by actor"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`actor_type` string Required The type of the actor Can be one of: `installation`, `classic_pat`, `fine_grained_pat`, `oauth_app`, `_app_user_to_server`
`actor_id` integer Required The ID of the actor

Query parameters
Name, Type, Description
`min_timestamp` string Required The minimum timestamp to query for stats. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`max_timestamp` string The maximum timestamp to query for stats. Defaults to the time 30 days ago. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`timestamp_increment` string Required The increment of time used to breakdown the query results (5m, 10m, 1h, etc.)

HTTP response status codes for "Get time stats by actor"

Status code	Description
`200`	OK

Code samples for "Get time stats by actor"

If you access at GHE.com, replace api..com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/insights/api/time-stats/{actor_type}/{actor_id}

curl -L \ -H "Accept: application/vnd.+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X--Api-Version: 2022-11-28" \ "https://api..com/orgs/ORG/insights/api/time-stats/ACTOR_TYPE/ACTOR_ID?min_timestamp=MIN_TIMESTAMP&timestamp_increment=TIMESTAMP_INCREMENT"

Response

Status: 200

[ { "timestamp": "2024-09-11T15:00:00Z", "total_request_count": 34225, "rate_limited_request_count": 0 }, { "timestamp": "2024-09-11T15:05:00Z", "total_request_count": 10587, "rate_limited_request_count": 18 }, { "timestamp": "2024-09-11T15:10:00Z", "total_request_count": 43587, "rate_limited_request_count": 14 }, { "timestamp": "2024-09-11T15:15:00Z", "total_request_count": 19463, "rate_limited_request_count": 4 }, { "timestamp": "2024-09-11T15:20:00Z", "total_request_count": 60542, "rate_limited_request_count": 3 }, { "timestamp": "2024-09-11T15:25:00Z", "total_request_count": 55872, "rate_limited_request_count": 23 } ]

Get API usage statistics within an organization for a user broken down by the type of access.

Fine-grained access tokens for "Get user stats"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"API Insights" organization permissions (read)

Parameters for "Get user stats"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`user_id` string Required The ID of the user to query for stats

Query parameters
Name, Type, Description
`min_timestamp` string Required The minimum timestamp to query for stats. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`max_timestamp` string The maximum timestamp to query for stats. Defaults to the time 30 days ago. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`direction` string The direction to sort the results by. Default: `desc` Can be one of: `asc`, `desc`
`sort` array The property to sort the results by.
`actor_name_substring` string Providing a substring will filter results where the actor name contains the substring. This is a case-insensitive search.

HTTP response status codes for "Get user stats"

Status code	Description
`200`	OK

Code samples for "Get user stats"

If you access at GHE.com, replace api..com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/insights/api/user-stats/{user_id}

curl -L \ -H "Accept: application/vnd.+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X--Api-Version: 2022-11-28" \ "https://api..com/orgs/ORG/insights/api/user-stats/USER_ID?min_timestamp=MIN_TIMESTAMP"

Response

Status: 200

[ { "actor_type": "oauth_app", "actor_id": 954453, "actor_name": " Actions", "oauth_application_id": 1245, "total_request_count": 544665, "rate_limited_request_count": 13, "last_request_timestamp": "2024-09-18T15:43:03Z", "last_rate_limited_timestamp": "2024-09-18T06:30:09Z" } ]