Cisco Umbrella API Usage Reports
Get the Umbrella API usage reports for an organization.
OpenAPI Specification
openapi: 3.0.0
info:
title: Cisco Umbrella API Usage Reports
version: 2.0.0
description: Get the Umbrella API usage reports for an organization.
contact:
name: Cloud Security Developer Community
x-provenance:
method: harvested
authored_by: Cisco Umbrella
harvested_by: API Evangelist
harvested_on: '2026-08-19'
first_party: true
provider_published: true
source_host: pubhub.devnetcloud.com
note: 26 first-party OpenAPI 3.0 documents (256 operations) listed by Cisco's own docs-nav config and fetched anonymously.
Byte-identity reconfirmed 2026-08-19 by SHA-256 against the live source.
x-evidence:
- type: source
url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/umbrella-config.json
- type: source
url: https://developer.cisco.com/docs/cloud-security/
servers:
- url: https://api.umbrella.com/{basePath}
variables:
basePath:
default: reports/v2
tags:
- name: API Usage Report
description: API Usage reports
- name: Umbrella
security:
- oauthFlow: []
paths:
/apiUsage/requests:
get:
operationId: getAPIUsageRequests
summary: Get Requests
description: 'Get the information about the API requests for the organization within a specific time period, including
the total number of API requests for the type of client program.'
tags:
- API Usage Report
- Umbrella
security:
- oauthFlow:
- reports.apiusage:read
parameters:
- $ref: '#/components/parameters/from'
- $ref: '#/components/parameters/to'
- $ref: '#/components/parameters/apiKeys'
- $ref: '#/components/parameters/paths'
- $ref: '#/components/parameters/verbs'
- $ref: '#/components/parameters/statusCodes'
- $ref: '#/components/parameters/userAgents'
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/requests'
example:
from: '2023-12-03'
to: '2023-12-04'
count: 100
items:
- userAgent: python-requests/2.20.0
count: 2529
requests:
- path: auth/v2/token
verb: POST
count: 928
- path: /reports/v2/activity/proxy
verb: GET
count: 801
- path: /reports.us/v2/activity/proxy
verb: GET
count: 800
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
/apiUsage/responses:
get:
operationId: getAPIUsageResponses
summary: Get Responses
description: 'Get the information about the API responses for the organization within a specific time period, including
the total number of API responses and the HTTP status codes.'
tags:
- API Usage Report
- Umbrella
security:
- oauthFlow:
- reports.apiusage:read
parameters:
- $ref: '#/components/parameters/from'
- $ref: '#/components/parameters/to'
- $ref: '#/components/parameters/apiKeys'
- $ref: '#/components/parameters/paths'
- $ref: '#/components/parameters/verbs'
- $ref: '#/components/parameters/statusCodes'
- $ref: '#/components/parameters/userAgents'
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/responses'
example:
from: '2023-12-03'
to: '2023-12-04'
count: 566
items:
- statusCode: '401'
count: 566
requests:
- path: /deployments/v2/networks
verb: GET
count: 546
- path: /deployments/v2/virtualappliances
verb: POST
count: 16
- path: /deployments/v2/internaldomains
verb: GET
count: 4
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
/apiUsage/keys:
get:
operationId: getAPIUsageKeys
summary: Get Keys
description: Get the API key usage information, including the total number of API requests within a specific time period.
tags:
- API Usage Report
- Umbrella
security:
- oauthFlow:
- reports.apiusage:read
parameters:
- $ref: '#/components/parameters/from'
- $ref: '#/components/parameters/to'
- $ref: '#/components/parameters/apiKeys'
- $ref: '#/components/parameters/paths'
- $ref: '#/components/parameters/verbs'
- $ref: '#/components/parameters/statusCodes'
- $ref: '#/components/parameters/userAgents'
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/keys'
example:
from: '2023-12-03'
to: '2023-12-04'
count: 566
items:
- keyName: Deployments API key
keyId: 124afg
count: 5000
requests:
- path: /deployments/v2/roamingcomputers
verb: GET
count: 4
- path: /deployments/v2/networks
verb: GET
count: 10
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
/apiUsage/summary:
get:
operationId: getAPIUsageSummary
summary: Get Summary
description: Get the total number API requests, and the counts of the successful and failed API requests within a specific
time period.
tags:
- API Usage Report
- Umbrella
security:
- oauthFlow:
- reports.apiusage:read
parameters:
- $ref: '#/components/parameters/from'
- $ref: '#/components/parameters/to'
- $ref: '#/components/parameters/apiKeys'
- $ref: '#/components/parameters/paths'
- $ref: '#/components/parameters/verbs'
- $ref: '#/components/parameters/statusCodes'
- $ref: '#/components/parameters/userAgents'
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/summary'
example:
data:
successfulRequests: 20
failedRequests: 5
total: 25
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
components:
headers:
Content-Type:
schema:
type: string
description: The MIME content type of the response body.
example: application/json
Date:
schema:
type: string
pattern: ^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$
description: The timestamp of the response.
example: '2023-03-14T18:34:25Z'
parameters:
from:
name: from
in: query
description: 'The date and time specified in the RFC-3339 format, for example: 2023-10-01.
Filter the collection for data that appears after this time.'
required: true
schema:
type: string
example: '2023-10-01'
to:
name: to
in: query
description: 'The date and time specified in the RFC-3339 format, for example: 2023-10-01.
Filter the collection for data that appears before this time.'
required: true
schema:
type: string
example: '2023-10-01'
apiKeys:
name: apiKeys
in: query
description: Sort the collection using a list of comma-separated API key IDs.
required: false
schema:
type: string
example: 123abfs77632
verbs:
name: verbs
in: query
description: 'Sort the collection using a list of comma-separated HTTP verbs.
The HTTP verb strings are case sensitive.'
required: false
schema:
type: string
example: GET,POST,PUT
paths:
name: paths
in: query
description: Sort the collection using a list of comma-separated API resource paths.
required: false
schema:
type: string
example: policies/v2/destinationlists/1234556,policies/v2/destinationlists
statusCodes:
name: statusCodes
in: query
description: Sort the collection using a list of comma-separated HTTP status codes.
required: false
schema:
type: string
example: 200,204,429
userAgents:
name: userAgents
in: query
description: Sort the collection using a list of comma-separated labels that describe the HTTP client programs.
required: false
schema:
type: string
example: python-requests/2.20.0,Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0
Safari/537.36
schemas:
count:
type: integer
format: int32
description: The total number of API requests.
example: 450
from:
type: string
description: The date and time where to start reading in the collection.
example: '2023-12-03'
to:
type: string
description: The date and time where to stop reading in the collection.
example: '2023-12-05'
message:
type: string
description: The description of the error.
example: Internal Server Error
code:
type: integer
description: The status code of the error.
example: 500
response:
type: object
properties:
meta:
type: object
example: {}
data:
type: object
properties:
errors:
type: string
description: The information about the error condition.
example: missing required parameters
requiredParameters:
type: array
description: The list of query parameters that you must include in the API request.
items:
type: string
description: The name of the query parameters on the API endpoint.
example: to
example:
- from
- to
example:
meta: {}
data:
errors: missing required parameters
requiredParameters:
- to
- from
requestsInformation:
type: array
description: The information about the API requests.
items:
type: object
required:
- userAgent
- count
- requests
properties:
userAgent:
type: string
description: The name of the client program.
example: python-requests/2.20.0
count:
$ref: '#/components/schemas/count'
requests:
$ref: '#/components/schemas/requestDetailsList'
example:
- userAgent: python-requests/2.20.0
count: 2529
requests:
- path: auth/v2/token
verb: POST
count: 928
- path: /reports/v2/activity/proxy
verb: GET
count: 801
- path: /reports.us/v2/activity/proxy
verb: GET
count: 800
- userAgent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36
count: 13
requests:
- path: /policies/v2/destinationlists
verb: GET
count: 13
requestDetailsList:
type: array
description: The list of API request information.
items:
type: object
required:
- path
- verb
- count
properties:
path:
type: string
description: The path of the API endpoint.
example: /reports/v2/activity/proxy
verb:
type: string
description: The name of the API operation.
example: GET
count:
type: integer
description: The number of requests to the API endpoint.
format: int64
example: 928
example:
path: /auth/v2/token
verb: POST
count: 928
example:
- path: /auth/v2/token
verb: POST
count: 928
responsesInformation:
type: array
description: The list of information about API responses for the API requests.
items:
type: object
required:
- statusCode
- count
- requests
properties:
statusCode:
type: string
description: The HTTP response status code.
example: '204'
count:
$ref: '#/components/schemas/count'
requests:
$ref: '#/components/schemas/requestDetailsList'
example:
- statusCode: '302'
count: 2667
requests:
- path: /reports/v2/activity/proxy
verb: GET
count: 2667
- statusCode: '200'
count: 6000
requests:
- path: /auth/v2/token
verb: POST
count: 4204
- path: /reports.us/v2/activity/proxy
verb: GET
count: 2661
- statusCode: '401'
count: 566
requests:
- path: /policies/v2/destinationlists
verb: GET
count: 546
- path: /policies/v2/destinationlists
verb: POST
count: 16
- path: /policies/v2/destinationlists/{destinationListId}
verb: GET
count: 4
requests:
type: object
description: The information about the API requests.
required:
- from
- to
- count
- items
properties:
from:
$ref: '#/components/schemas/from'
to:
$ref: '#/components/schemas/to'
count:
$ref: '#/components/schemas/count'
items:
$ref: '#/components/schemas/requestsInformation'
example:
from: '2023-12-03'
to: '2023-12-04'
count: 100
items:
- userAgent: python-requests/2.20.0
count: 2529
requests:
- path: auth/v2/token
verb: POST
count: 928
- path: /reports/v2/activity/proxy
verb: GET
count: 801
- path: /reports.us/v2/activity/proxy
verb: GET
count: 800
responses:
type: object
description: The information about the API responses.
required:
- from
- to
- count
- items
properties:
from:
$ref: '#/components/schemas/from'
to:
$ref: '#/components/schemas/to'
count:
$ref: '#/components/schemas/count'
items:
$ref: '#/components/schemas/responsesInformation'
example:
from: '2023-12-03'
to: '2023-12-04'
count: 100
items:
- statusCode: '401'
count: 566
requests:
- path: /reports/v2/activity/proxy
verb: GET
count: 546
- path: /deployments/v2/networks
verb: POST
count: 16
- path: /deployments/v2/roamingcomputers
verb: GET
count: 4
keysInformation:
type: array
description: The information about the API key usage.
items:
type: object
required:
- count
- requests
- keyName
- keyId
properties:
keyName:
type: string
description: The name of the API key.
example: Deployments API key
keyId:
type: string
description: The ID of the API key.
example: 12345345345a
count:
$ref: '#/components/schemas/count'
requests:
$ref: '#/components/schemas/requestDetailsList'
example:
- keyName: Reports and Policies API key
keyId: ajsdk12455555
count: 400
requests:
- path: /reports/v2/activity/proxy
verb: GET
count: 546
- path: /policies/v2/destinationlists
verb: POST
count: 16
- path: /policies/v2/destinationlists
verb: GET
count: 4
keys:
type: object
description: The information about the API key usage.
required:
- from
- to
- count
- items
properties:
from:
$ref: '#/components/schemas/from'
to:
$ref: '#/components/schemas/to'
count:
$ref: '#/components/schemas/count'
items:
$ref: '#/components/schemas/keysInformation'
example:
from: '2023-12-03'
to: '2023-12-04'
count: 100
items:
- keyName: Reports and Policies API key
keyId: ajsdk12455555
count: 400
requests:
- path: /reports/v2/activity/proxy
verb: GET
count: 546
- path: /policies/v2/destinationlists
verb: POST
count: 16
- path: /policies/v2/destinationlists
verb: GET
count: 4
summary:
type: object
description: The summary of the API usage.
required:
- data
properties:
data:
type: object
description: The total number of requsts and the counts of the failed and successful requests.
required:
- successfulRequests
- failedRequests
- total
properties:
successfulRequests:
type: integer
description: The number of successful API requests.
example: 20
failedRequests:
type: integer
description: The number of failed API requests.
example: 5
total:
type: integer
description: The total number of API requests.
example: 25
example:
data:
successfulRequests: 20
failedRequests: 5
total: 25
securitySchemes:
oauthFlow:
type: oauth2
description: Client credential flow
flows:
clientCredentials:
tokenUrl: https://api.umbrella.com/auth/v2/token
scopes:
reports.apiusage:read: Read the API Usage reports
responses:
400Error:
description: Bad Request
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
type: object
properties:
message:
$ref: '#/components/schemas/message'
code:
$ref: '#/components/schemas/code'
example:
message: Bad Request
code: 400
400ErrorMissingParams:
description: Bad Request
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/response'
example:
meta: {}
data:
errors: Missing required parameters
requiredParameters:
- from
- to
401Error:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
$ref: '#/components/schemas/message'
code:
$ref: '#/components/schemas/code'
example:
message: Unauthorized
code: 401
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
403Error:
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
$ref: '#/components/schemas/message'
code:
$ref: '#/components/schemas/code'
example:
message: Forbidden
code: 403
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
404Error:
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
$ref: '#/components/schemas/message'
code:
$ref: '#/components/schemas/code'
example:
message: Not Found
code: 404
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
500Error:
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
message:
$ref: '#/components/schemas/message'
code:
$ref: '#/components/schemas/code'
example:
message: Internal Server Error
code: 500
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
x-provenance:
method: harvested
first_party: true
harvested: '2026-08-19'
source: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/reports/api-usage.yaml
publisher: Cisco Systems, Inc. (Cisco DevNet Cloud Security docs)
x-evidence:
fetched: '2026-08-19'
url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/reports/api-usage.yaml
http_status: 200
docs: https://developer.cisco.com/docs/cloud-security/