read thedocs.

[ docs // guides & reference ]

Connector setup guides, tool references, auth flows, and platform concepts — everything you need to run StackJack, in one place.

Browse the Docs All Connectors
34 connectors documented // 6,712 tools referenced // setup, auth & platform guides
↓

No pages match that search. Clear it

← All documentation

Cisco Umbrella Tools

umb_ · 233 tools · Free 140 · Pro 93 OAuth2 client-credentials (Basic-auth token endpoint, cached tokens); host-only BaseAddress so every path carries its scope-family prefix (admin/deployments/policies/reports/investigate v2); two pagination models (page+limit for management, limit+offset for reports/investigate); max page size 1000; Investigate tools require the Umbrella Investigate add-on license (403/404 without); raw JSON passthrough.

Admin

Tool Plan Access Description
umb_create_user Pro Write [Cisco Umbrella] Create an administrator user in your Umbrella organization. Provide a JSON object body with required fields firstname, lastname, email, and roleId (from umb_list_roles); optional password and timezone. The body contains a password — handle it as a secret. A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.
umb_delete_user Pro Destructive [Cisco Umbrella] Delete an administrator user from your Umbrella organization by userId (from umb_list_users). This permanently removes the user. A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.
umb_get_user Free Read-only [Cisco Umbrella] Get a single administrator user by id. Returns the user's full detail (name, email, role, status). Discover userId with umb_list_users.
umb_list_roles Free Read-only [Cisco Umbrella] List the administrator roles available in your Umbrella organization. Returns each role's id and label. Use the returned roleId when creating an administrator with umb_create_user.
umb_list_users Free Read-only [Cisco Umbrella] List the administrator users in your Umbrella organization. Returns each user's id, name, email, and role. Paginated with page + limit (limit capped at 1000). Use umb_get_user for one user's full detail and the returned userId with umb_delete_user.
umb_rotate_s3_bucket_key Pro Destructive [Cisco Umbrella] Rotate the S3 bucket access key for your organization's managed S3 log storage. This mints a NEW secretAccessKey and immediately invalidates the previous one — the response returns the new secretAccessKey, so handle it as a secret / credential material. Cisco mandates rotating this key at least every 90 days. Takes no parameters. Vendor scope: Admin > IAM (admin.iam:write). A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.
umb_create_user parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: firstname, lastname, email, roleId (from umb_list_roles). Optional: password, timezone.
umb_delete_user parameters
Param Type Required Default Description
userId string yes The id of the user to delete (from umb_list_users).
umb_get_user parameters
Param Type Required Default Description
userId string yes The id of the user (from umb_list_users).
umb_list_users parameters
Param Type Required Default Description
limit integer no 100 The number of records to return per page (default 100, max 1000).
page integer no 1 The number of the page to return (default 1).

API Keys

Tool Plan Access Description
umb_create_api_key Pro Write [Cisco Umbrella] Create an API key. Provide a JSON object body with required fields name and scopes (array of scope strings); optional description, expireAt, and allowedIPs (array of IP addresses / CIDR blocks). Returns the new key and its secret (shown once). A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.
umb_delete_api_key Pro Destructive [Cisco Umbrella] Delete an API key by apiKeyId (from umb_list_api_keys). This permanently revokes the key. A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.
umb_get_api_key Free Read-only [Cisco Umbrella] Get a single API key by apiKeyId (from umb_list_api_keys). Returns the key's name, scopes, allowed IPs, and expiration (never the secret).
umb_list_api_keys Free Read-only [Cisco Umbrella] List the API keys created by your organization. Returns each key's id, name, scopes, and expiration (never the secret). Paginated with limit + offset (limit capped at 1000). Use umb_get_api_key for one key's detail and the returned apiKeyId with umb_update_api_key, umb_delete_api_key, or umb_refresh_api_key.
umb_refresh_api_key Pro Destructive [Cisco Umbrella] Refresh an API key, rotating its secret. Identify the key by apiKeyId (from umb_list_api_keys); no request body. Returns the key with its new secret (shown once). WARNING: rotating a key immediately invalidates its current secret, so EVERY consumer of that key stops working until it is reconfigured with the new secret — no in-use key is safe to rotate blindly. Rotating the key StackJack itself uses for this Umbrella connector is a known self-outage: the one-time secret Umbrella returns is NOT saved back to StackJack's stored connector credentials, so you must manually re-save it in the Portal to restore access. Rotating any OTHER in-use key (other integrations, scripts, dashboards) likewise breaks those consumers until each is updated with the new secret wherever the key is consumed. A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.
umb_update_api_key Pro Write [Cisco Umbrella] Update an API key's name, description, scopes, and allowed IPs. Identify the key by apiKeyId (from umb_list_api_keys) and provide a JSON object body with required fields name and scopes (array); optional description and allowedIPs (array). A 403 means the API key lacks the edit:admin (write) scope — re-issue the Umbrella API key with that scope.
umb_create_api_key parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: name, scopes (array). Optional: description, expireAt, allowedIPs (array of IPs/CIDR blocks).
umb_delete_api_key parameters
Param Type Required Default Description
apiKeyId string yes The id of the API key to delete (from umb_list_api_keys).
umb_get_api_key parameters
Param Type Required Default Description
apiKeyId string yes The id of the API key (from umb_list_api_keys).
umb_list_api_keys parameters
Param Type Required Default Description
limit integer no 100 The number of items to return in the page (default 100, max 1000).
offset integer no 0 The place to start reading in the collection (default 0).
umb_refresh_api_key parameters
Param Type Required Default Description
apiKeyId string yes The id of the API key to refresh (from umb_list_api_keys).
umb_update_api_key parameters
Param Type Required Default Description
apiKeyId string yes The id of the API key to update (from umb_list_api_keys).
fieldsJson string yes JSON object body. Required: name, scopes (array). Optional: description, allowedIPs (array).

Networks

Tool Plan Access Description
umb_create_internal_network Pro Write [Cisco Umbrella] Create an internal network. Provide a JSON object body with required fields name, ipAddress, and prefixLength; optional siteId, networkId, and tunnelId to associate it (discover those with umb_list_sites, umb_list_networks, and the tunnels tools). A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.
umb_create_network Pro Write [Cisco Umbrella] Create a network (external/egress IP range). Provide a JSON object body with required fields name, prefixLength, isDynamic, and status; optional ipAddress. Note: before creating a network you must contact Cisco Support to get your IP range verified. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.
umb_delete_internal_network Pro Destructive [Cisco Umbrella] Delete an internal network by its origin id (internalNetworkId, from umb_list_internal_networks). This permanently removes the internal network. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.
umb_delete_network Pro Destructive [Cisco Umbrella] Delete a network by networkId (from umb_list_networks). This permanently removes the network from your deployment. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.
umb_get_internal_network Free Read-only [Cisco Umbrella] Get a single internal network by its origin id (internalNetworkId, from umb_list_internal_networks). Returns the internal network's name, IP address/prefix, and associations.
umb_get_network Free Read-only [Cisco Umbrella] Get a single network by networkId (from umb_list_networks). Returns the network's name, IP address/prefix, dynamic flag, and status.
umb_list_internal_network_policies Free Read-only [Cisco Umbrella] List the policies applied to an internal network by its origin id (internalNetworkId, from umb_list_internal_networks). Optional type selects the policy family — dns or web. Vendor scope: deployments.internalnetworks:read.
umb_list_internal_networks Free Read-only [Cisco Umbrella] List the internal networks defined in your Umbrella deployment. Returns each internal network's id, name, IP address/prefix, and any associated site/network/tunnel. Optionally filter by name. Paginated with page + limit (limit capped at 1000). Use umb_get_internal_network for one record's detail and the returned id with umb_update_internal_network or umb_delete_internal_network.
umb_list_network_policies Free Read-only [Cisco Umbrella] List the policies applied to a network by its networkId (from umb_list_networks). Optional type selects the policy family — dns or web. Vendor scope: deployments.networks:read.
umb_list_networks Free Read-only [Cisco Umbrella] List the networks (external/egress IP ranges) registered in your Umbrella deployment. Returns each network's id, name, IP address/prefix, and status. Paginated with page + limit (limit capped at 1000). Use umb_get_network for one network's detail and the returned networkId with umb_update_network or umb_delete_network.
umb_update_internal_network Pro Write [Cisco Umbrella] Update an internal network. Identify it by its origin id (internalNetworkId, from umb_list_internal_networks) and provide a JSON object body with required fields name, ipAddress, and prefixLength; optional siteId, networkId, and tunnelId. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.
umb_update_network Pro Write [Cisco Umbrella] Update a network. Identify it by networkId (from umb_list_networks) and provide a JSON object body with required fields name, isDynamic, and status; optional ipAddress and prefixLength. Note: before changing the network's IP address you must contact Cisco Support to get your IP range verified. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.
umb_create_internal_network parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: name, ipAddress, prefixLength. Optional: siteId, networkId, tunnelId.
umb_create_network parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: name, prefixLength, isDynamic, status. Optional: ipAddress.
umb_delete_internal_network parameters
Param Type Required Default Description
internalNetworkId string yes The origin id of the internal network to delete (from umb_list_internal_networks).
umb_delete_network parameters
Param Type Required Default Description
networkId string yes The id of the network to delete (from umb_list_networks).
umb_get_internal_network parameters
Param Type Required Default Description
internalNetworkId string yes The origin id of the internal network (from umb_list_internal_networks).
umb_get_network parameters
Param Type Required Default Description
networkId string yes The id of the network (from umb_list_networks).
umb_list_internal_network_policies parameters
Param Type Required Default Description
internalNetworkId string yes The origin id of the internal network (from umb_list_internal_networks).
type string no null Policy family to return: dns or web. Omit for the server default.
umb_list_internal_networks parameters
Param Type Required Default Description
limit integer no 100 The number of records to return per page (default 100, max 1000).
name string no null Optional internal-network label to filter by.
page integer no 1 The number of the page to return (default 1).
umb_list_network_policies parameters
Param Type Required Default Description
networkId string yes The id of the network (from umb_list_networks).
type string no null Policy family to return: dns or web. Omit for the server default.
umb_list_networks parameters
Param Type Required Default Description
limit integer no 100 The number of records to return per page (default 100, max 1000).
page integer no 1 The number of the page to return (default 1).
umb_update_internal_network parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: name, ipAddress, prefixLength. Optional: siteId, networkId, tunnelId.
internalNetworkId string yes The origin id of the internal network to update (from umb_list_internal_networks).
umb_update_network parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: name, isDynamic, status. Optional: ipAddress, prefixLength.
networkId string yes The id of the network to update (from umb_list_networks).

Sites

Tool Plan Access Description
umb_create_site Pro Write [Cisco Umbrella] Create a site. Provide a JSON object body with the required field name. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.
umb_delete_site Pro Destructive [Cisco Umbrella] Delete a site by siteId (from umb_list_sites). This permanently removes the site. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.
umb_get_site Free Read-only [Cisco Umbrella] Get a single site by siteId (from umb_list_sites). Returns the site's name and origin id.
umb_list_sites Free Read-only [Cisco Umbrella] List the sites in your Umbrella organization. Returns each site's id, name, and origin id. Paginated with page + limit (limit capped at 1000). Use umb_get_site for one site's detail and the returned siteId with umb_update_site or umb_delete_site.
umb_update_site Pro Write [Cisco Umbrella] Update a site. Identify it by siteId (from umb_list_sites) and provide a JSON object body with the required field name. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.
umb_create_site parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: name.
umb_delete_site parameters
Param Type Required Default Description
siteId string yes The id of the site to delete (from umb_list_sites).
umb_get_site parameters
Param Type Required Default Description
siteId string yes The id of the site (from umb_list_sites).
umb_list_sites parameters
Param Type Required Default Description
limit integer no 100 The number of records to return per page (default 100, max 1000).
page integer no 1 The number of the page to return (default 1).
umb_update_site parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: name.
siteId string yes The id of the site to update (from umb_list_sites).

Tunnels

Tool Plan Access Description
umb_create_tunnel Pro Write [Cisco Umbrella] Add a new network tunnel to the organization. Provide the tunnel as a JSON object in fieldsJson — required: name; optional: siteOriginId, deviceType, serviceType, networkCIDRs, transport, authentication (data-center choices come from umb_list_tunnel_datacenters). A 403 means the API key lacks the deployments write scope — re-issue the Umbrella API key with edit:deployments.
umb_delete_tunnel Pro Destructive [Cisco Umbrella] Permanently delete a network tunnel by its numeric id (from umb_list_tunnels). If the tunnel is attached to policies, set detachPolicies=true to detach it during deletion. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.
umb_get_tunnel Free Read-only [Cisco Umbrella] Get a single network tunnel by its numeric id (from umb_list_tunnels). Returns the tunnel's full configuration including name, siteOriginId, device/service type, network CIDRs, transport, and authentication metadata.
umb_get_tunnel_events Free Read-only [Cisco Umbrella] Get recent events for a network tunnel by its numeric id (from umb_list_tunnels). Optional hour (1-168) selects the lookback window, limit (1-500, capped at 500) caps the page size, and cursor pages forward. Returns a single {meta,data} object. Vendor scope: deployments.tunnels:read.
umb_get_tunnel_global_events Free Read-only [Cisco Umbrella] Get global events for a network tunnel (by numeric id, from umb_list_tunnels) filtered to a specific source IP. The ip is a required path segment. Optional hour (1-168), limit (1-500, capped at 500), and cursor page forward. Returns an array of {meta,data} objects. Vendor scope: deployments.tunnels:read.
umb_get_tunnel_state Free Read-only [Cisco Umbrella] Get the live state information for a single network tunnel by its numeric id (from umb_list_tunnels) — up/down status and connection detail for that one tunnel.
umb_list_tunnel_datacenters Free Read-only [Cisco Umbrella] List the IPsec-enabled Umbrella data centers available for tunnel termination. Each entry includes the data center's IP address and location details — use these when choosing a data center for umb_create_tunnel.
umb_list_tunnel_policies Free Read-only [Cisco Umbrella] List the policies attached to a network tunnel by its numeric id (from umb_list_tunnels). Optional type selects the policy family — firewallrule or web (note: this endpoint uses firewallrule|web, NOT dns|web). Page with page + limit (limit capped at 1000). Vendor scope: deployments.tunnels:read.
umb_list_tunnel_states Free Read-only [Cisco Umbrella] List the live state information for all network tunnels in the organization (up/down status and connection details across every tunnel). For one tunnel's state, use umb_get_tunnel_state.
umb_list_tunnels Free Read-only [Cisco Umbrella] List the network tunnels (IPsec) configured for the organization. Returns each tunnel's id, name, device/service type, data center, and status. Set includeState=true to embed live tunnel state. Cursor pagination: pass a bounded limit and, to page, the startKey returned in the Link header of the prior response. Use filters (a JSON object string) to narrow by name/deviceType/serviceType/status/dataCenter/siteOriginId. Tunnel ids feed umb_get_tunnel, umb_update_tunnel, and umb_delete_tunnel.
umb_rotate_tunnel_credentials Pro Destructive [Cisco Umbrella] Rotate the IPsec pre-shared key (PSK) credentials for a network tunnel by its numeric id (from umb_list_tunnels). Provide a JSON object in fieldsJson — required: autoRotate (boolean); when autoRotate is false you MUST supply psk.idPrefix. Optional deprecateCurrentKeys=true deletes the current key immediately; otherwise the current PSK is invalidated but retained for 24h. WARNING: this invalidates the current PSK and RETURNS THE NEW SECRET in the response (treat it as credential material). Vendor scope: deployments.tunnels:write. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.
umb_update_tunnel Pro Write [Cisco Umbrella] Update a network tunnel by its numeric id (from umb_list_tunnels). Provide the changes as a JSON object in fieldsJson — required: name and client; updatable: name, siteOriginId, networkCIDRs, client (deviceType). Updates to read-only attributes are ignored. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.
umb_create_tunnel parameters
Param Type Required Default Description
fieldsJson string yes JSON object for the new tunnel. Required: name. Optional: siteOriginId, deviceType, serviceType, networkCIDRs, transport, authentication.
umb_delete_tunnel parameters
Param Type Required Default Description
detachPolicies boolean no null Detach the tunnel from any attached policies as part of deletion. Omit to attempt deletion without detaching.
id string yes The numeric id of the tunnel to delete (from umb_list_tunnels).
umb_get_tunnel parameters
Param Type Required Default Description
id string yes The numeric id of the tunnel (from umb_list_tunnels).
umb_get_tunnel_events parameters
Param Type Required Default Description
cursor string no null Cursor for the next page (from the prior response). Omit for the first page.
hour integer no null Lookback window in hours (1-168). Omit for the server default.
id string yes The numeric id of the tunnel (from umb_list_tunnels).
limit integer no null Max events to return per page (1-500, capped at 500). Omit for the server default.
umb_get_tunnel_global_events parameters
Param Type Required Default Description
cursor string no null Cursor for the next page (from the prior response). Omit for the first page.
hour integer no null Lookback window in hours (1-168). Omit for the server default.
id string yes The numeric id of the tunnel (from umb_list_tunnels).
ip string yes The source IP address to filter events by (required).
limit integer no null Max events to return per page (1-500, capped at 500). Omit for the server default.
umb_get_tunnel_state parameters
Param Type Required Default Description
id string yes The numeric id of the tunnel (from umb_list_tunnels).
umb_list_tunnel_policies parameters
Param Type Required Default Description
id string yes The numeric id of the tunnel (from umb_list_tunnels).
limit integer no null Records per page (capped at 1000). Omit for the server default.
page integer no null Page number in the collection. Omit for the first page.
type string no null Policy family to return: firewallrule or web. Omit for the server default.
umb_list_tunnels parameters
Param Type Required Default Description
filters string no null Optional JSON object string to filter results, e.g. {"name":"test","deviceType":"ISR","serviceType":"SIG","status":"UP","dataCenter":"pao1.edc","siteOriginId":123}.
includeState boolean no null Include per-tunnel live state in each item (default false).
limit integer no null Max tunnels to return (capped at 1000). Omit to return all tunnels.
startKey string no null Cursor for the next page — the startKey value from the prior response's Link header. Omit for the first page.
umb_rotate_tunnel_credentials parameters
Param Type Required Default Description
fieldsJson string yes JSON object controlling the rotation. Required: autoRotate (boolean). If autoRotate is false, you must supply psk.idPrefix. Optional: deprecateCurrentKeys (true deletes the current PSK immediately instead of the default 24h retention).
id string yes The numeric id of the tunnel whose credentials to rotate (from umb_list_tunnels).
umb_update_tunnel parameters
Param Type Required Default Description
fieldsJson string yes JSON object of tunnel fields to update. Required: name, client. Updatable: name, siteOriginId, networkCIDRs, client.
id string yes The numeric id of the tunnel to update (from umb_list_tunnels).

Internal Domains

Tool Plan Access Description
umb_add_internal_domains Pro Write [Cisco Umbrella] Add (create) an internal domain. Provide a JSON object body with the required field domain; optional description, includeAllVAs (bool), includeAllMobileDevices (bool), and siteIds (array of site ids from umb_list_sites). If you omit siteIds, the internal domain is associated with all sites in the organization. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.
umb_delete_internal_domain Pro Destructive [Cisco Umbrella] Delete an internal domain by internalDomainId (from umb_list_internal_domains). This permanently removes the internal domain. A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.
umb_get_internal_domain Free Read-only [Cisco Umbrella] Get a single internal domain by internalDomainId (from umb_list_internal_domains). Returns the domain, description, and site associations.
umb_list_internal_domains Free Read-only [Cisco Umbrella] List the internal domains configured for your Umbrella deployment (domains excluded from DNS redirection). Returns each internal domain's id, domain, description, and site associations. Paginated with page + limit (limit capped at 1000). Use umb_get_internal_domain for one record's detail and the returned id with umb_update_internal_domain or umb_delete_internal_domain.
umb_update_internal_domain Pro Write [Cisco Umbrella] Update an internal domain. Identify it by internalDomainId (from umb_list_internal_domains) and provide a JSON object body with the required field domain; optional description, includeAllVAs (bool), includeAllMobileDevices (bool), and siteIds (array of site ids). A 403 means the API key lacks the edit:deployments (write) scope — re-issue the Umbrella API key with that scope.
umb_add_internal_domains parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: domain. Optional: description, includeAllVAs (bool), includeAllMobileDevices (bool), siteIds (array of site ids).
umb_delete_internal_domain parameters
Param Type Required Default Description
internalDomainId string yes The id of the internal domain to delete (from umb_list_internal_domains).
umb_get_internal_domain parameters
Param Type Required Default Description
internalDomainId string yes The id of the internal domain (from umb_list_internal_domains).
umb_list_internal_domains parameters
Param Type Required Default Description
limit integer no 100 The number of records to return per page (default 100, max 1000).
page integer no 1 The number of the page to return (default 1).
umb_update_internal_domain parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: domain. Optional: description, includeAllVAs (bool), includeAllMobileDevices (bool), siteIds (array of site ids).
internalDomainId string yes The id of the internal domain to update (from umb_list_internal_domains).

Devices & Tags

Tool Plan Access Description
umb_add_tags_to_devices Pro Write [Cisco Umbrella] Associate a device tag with one or more devices. Provide tagId (from umb_list_tags) and originIdsJson, a JSON array of device originIds to tag, e.g. [12345,67890]. Shares its endpoint with umb_remove_tags_from_devices; this tool sends the addOrigins body key. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.
umb_create_network_device Pro Write [Cisco Umbrella] Register a new network device (integrated router/firewall, e.g. Cisco ISR) in the organization. Provide the device as a JSON object in fieldsJson — required: model, macAddress (12 hex chars, no separators), name (1-50 chars), serialNumber. Vendor scope: deployments.networkdevices:write. A 403 means the API key lacks the deployments write scope — re-issue the Umbrella API key with edit:deployments.
umb_create_tag Pro Write [Cisco Umbrella] Create a new device tag in the organization. Provide the tag as a JSON object in fieldsJson — required: name (the tag label), e.g. {"name":"finance-laptops"}. The returned tag id is used by umb_add_tags_to_devices. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.
umb_delete_network_device Pro Destructive [Cisco Umbrella] Permanently delete (deregister) a network device from the organization by its numeric originId (from umb_list_network_devices). Vendor scope: deployments.networkdevices:write. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.
umb_delete_roaming_computer Pro Destructive [Cisco Umbrella] Permanently delete (deregister) a roaming computer from the organization by its deviceId (from umb_list_roaming_computers). A 403 means the API key lacks the deployments write scope — re-issue the Umbrella API key with edit:deployments.
umb_delete_virtual_appliance Pro Destructive [Cisco Umbrella] Permanently delete a virtual appliance (VA) from the organization by its numeric originId (virtualApplianceId, from umb_list_virtual_appliances). Vendor scope: deployments.virtualappliances:write. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.
umb_get_network_device Free Read-only [Cisco Umbrella] Get a single network device by its numeric originId (from umb_list_network_devices). Returns the device's full detail.
umb_get_roaming_computer Free Read-only [Cisco Umbrella] Get a single roaming computer by its deviceId (from umb_list_roaming_computers). Returns the device's full detail including DNS-layer and SWG status.
umb_get_roaming_computers_orginfo Free Read-only [Cisco Umbrella] Get organization-level roaming-computer information (org-wide roaming deployment metadata). Takes no parameters. Vendor scope: deployments.roamingcomputersOrgInfo:read — a plain deployments.roamingcomputers:read key returns 403 for this endpoint.
umb_get_virtual_appliance Free Read-only [Cisco Umbrella] Get a single Umbrella virtual appliance by its numeric originId (from umb_list_virtual_appliances). Returns the VA's full configuration and status.
umb_list_network_device_policies Free Read-only [Cisco Umbrella] List the policies applied to a network device by its numeric originId (from umb_list_network_devices). Optional type selects the policy family — dns or web (the server defaults to dns). Vendor scope: deployments.networkdevices:read.
umb_list_network_devices Free Read-only [Cisco Umbrella] List the network devices (integrated routers/firewalls, e.g. Cisco ISR) registered in the organization. Returns each device's originId, name, and model. Use umb_get_network_device for one device's detail.
umb_list_roaming_computers Free Read-only [Cisco Umbrella] List the roaming computers (Umbrella roaming client / SWG module devices) in the organization. Returns each computer's deviceId, name, DNS-layer status, and SWG (Secure Web Gateway) status. Filter by name, status (DNS-layer), swgStatus, and lastSync window (lastSyncBefore / lastSyncAfter timestamps). Page-based pagination. deviceId feeds umb_get_roaming_computer and umb_delete_roaming_computer.
umb_list_tags Free Read-only [Cisco Umbrella] List the device tags defined in the organization. Returns each tag's id and name. Tag ids feed umb_add_tags_to_devices and umb_remove_tags_from_devices. Page-based pagination (page + limit).
umb_list_virtual_appliances Free Read-only [Cisco Umbrella] List the Umbrella virtual appliances (VAs) deployed in the organization. Returns each VA's originId, name, version, and status. Page-based pagination (page + limit). VA originIds identify these devices as identities in umb_add_identity_to_policy.
umb_remove_tags_from_devices Pro Destructive [Cisco Umbrella] Remove a device tag association from one or more devices. Provide tagId (from umb_list_tags) and originIdsJson, a JSON array of device originIds to untag, e.g. [12345,67890]. Issues an HTTP DELETE on the shared /tags//devices path (the add sibling is a POST) with the removeOrigins body key. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.
umb_update_network_device Pro Write [Cisco Umbrella] Update a network device by its numeric originId (from umb_list_network_devices). Issues an HTTP PATCH; provide the changes as a JSON object in fieldsJson — required: name. Vendor scope: deployments.networkdevices:write. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.
umb_update_roaming_computer Pro Write [Cisco Umbrella] Update a roaming computer by its deviceId (a hex string, from umb_list_roaming_computers). Provide the changes as a JSON object in fieldsJson — required: name. Vendor scope: deployments.roamingcomputers:write. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.
umb_update_virtual_appliance Pro Write [Cisco Umbrella] Update a virtual appliance (VA) by its numeric originId (virtualApplianceId, from umb_list_virtual_appliances). Issues an HTTP PUT; provide the changes as a JSON object in fieldsJson — required: siteId. Vendor scope: deployments.virtualappliances:write. A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.
umb_add_tags_to_devices parameters
Param Type Required Default Description
originIdsJson string yes JSON array of device originIds to tag, e.g. [12345,67890].
tagId string yes The tag id to apply (from umb_list_tags).
umb_create_network_device parameters
Param Type Required Default Description
fieldsJson string yes JSON object for the new network device. Required: model, macAddress (12 hex chars, no separators), name (1-50 chars), serialNumber.
umb_create_tag parameters
Param Type Required Default Description
fieldsJson string yes JSON object for the new tag. Required: name (the tag label), e.g. {"name":"finance-laptops"}.
umb_delete_network_device parameters
Param Type Required Default Description
originId string yes The numeric originId of the network device to delete (from umb_list_network_devices).
umb_delete_roaming_computer parameters
Param Type Required Default Description
deviceId string yes The deviceId of the roaming computer to delete (from umb_list_roaming_computers).
umb_delete_virtual_appliance parameters
Param Type Required Default Description
virtualApplianceId string yes The numeric originId (virtualApplianceId) of the virtual appliance to delete (from umb_list_virtual_appliances).
umb_get_network_device parameters
Param Type Required Default Description
originId string yes The numeric originId of the network device (from umb_list_network_devices).
umb_get_roaming_computer parameters
Param Type Required Default Description
deviceId string yes The deviceId of the roaming computer (from umb_list_roaming_computers).
umb_get_virtual_appliance parameters
Param Type Required Default Description
virtualApplianceId string yes The numeric originId of the virtual appliance (from umb_list_virtual_appliances).
umb_list_network_device_policies parameters
Param Type Required Default Description
originId string yes The numeric originId of the network device (from umb_list_network_devices).
type string no null Policy family to return: dns or web. Omit to let the server default to dns.
umb_list_roaming_computers parameters
Param Type Required Default Description
lastSyncAfter string no null Return only computers whose last sync is after this timestamp.
lastSyncBefore string no null Return only computers whose last sync is before this timestamp.
limit integer no 100 Records per page (default 100, capped at 1000).
name string no null Filter by roaming computer name.
page integer no 1 Page number in the collection (default 1).
status string no null Filter by DNS-layer security status.
swgStatus string no null Filter by Internet security (Secure Web Gateway) status.
umb_list_tags parameters
Param Type Required Default Description
limit integer no 100 Records per page (default 100, capped at 1000).
page integer no 1 Page number in the collection (default 1).
umb_list_virtual_appliances parameters
Param Type Required Default Description
limit integer no 100 Records per page (default 100, capped at 1000).
page integer no 1 Page number in the collection (default 1).
umb_remove_tags_from_devices parameters
Param Type Required Default Description
originIdsJson string yes JSON array of device originIds to untag, e.g. [12345,67890].
tagId string yes The tag id to remove (from umb_list_tags).
umb_update_network_device parameters
Param Type Required Default Description
fieldsJson string yes JSON object of network-device fields to update. Required: name.
originId string yes The numeric originId of the network device to update (from umb_list_network_devices).
umb_update_roaming_computer parameters
Param Type Required Default Description
deviceId string yes The deviceId (hex string) of the roaming computer to update (from umb_list_roaming_computers).
fieldsJson string yes JSON object of roaming-computer fields to update. Required: name.
umb_update_virtual_appliance parameters
Param Type Required Default Description
fieldsJson string yes JSON object of virtual-appliance fields to update. Required: siteId.
virtualApplianceId string yes The numeric originId (virtualApplianceId) of the virtual appliance to update (from umb_list_virtual_appliances).

Destination Lists

Tool Plan Access Description
umb_add_destinations Pro Write [Cisco Umbrella] Add destination entries to a destination list, identified by its numeric id (from umb_list_destination_lists). Provide destinationsJson, a JSON array of objects — each requires destination (a domain, URL, or IP) and optionally a comment, e.g. [{"destination":"badsite.com","comment":"phishing"}]. A 403 means the API key lacks the policies write scope — re-issue the key with edit:policies.
umb_create_destination_list Pro Write [Cisco Umbrella] Create a destination list (allow or block list) in the organization. Provide the list as a JSON object in fieldsJson — required: access ("allow" or "block"), isGlobal (bool), name; optional: bundleTypeId, destinations (array of {destination, comment}). A 403 means the API key lacks the policies write scope — re-issue the Umbrella API key with edit:policies.
umb_delete_destination_list Pro Destructive [Cisco Umbrella] Permanently delete a destination list from the organization by its numeric id (from umb_list_destination_lists). A 403 means the API key lacks the policies write scope — re-issue the Umbrella API key with edit:policies.
umb_get_destination_list Free Read-only [Cisco Umbrella] Get a single destination list by its numeric id (from umb_list_destination_lists). Returns the list's metadata (name, access, isGlobal, bundleTypeId, destination count). For the entries themselves, use umb_list_destinations.
umb_list_destination_lists Free Read-only [Cisco Umbrella] List the destination lists (allow/block lists) in the organization. Returns each list's id, name, access (allow|block), and destination count. List ids feed umb_get_destination_list, umb_list_destinations, umb_update_destination_list, umb_delete_destination_list, umb_add_destinations, and umb_remove_destinations. Page-based pagination (page + limit).
umb_list_destinations Free Read-only [Cisco Umbrella] List the destination entries (domains, URLs, or IPs) inside a destination list, identified by its numeric id (from umb_list_destination_lists). Returns each entry's id, destination, type, and comment. The entry ids are what umb_remove_destinations deletes. Page-based pagination (page + limit).
umb_remove_destinations Pro Destructive [Cisco Umbrella] Remove destination entries from a destination list, identified by its numeric id (from umb_list_destination_lists). Provide destinationsJson, a JSON array of destination entry ids (NOT the domains) to delete, e.g. [123,456] — retrieve these ids via umb_list_destinations. Accepts at most 500 ids per call. A 403 means the API key lacks the policies write scope — re-issue the key with edit:policies.
umb_update_destination_list Pro Write [Cisco Umbrella] Rename a destination list by its numeric id (from umb_list_destination_lists). Provide the change as a JSON object in fieldsJson — required: name. To change the entries, use umb_add_destinations / umb_remove_destinations instead. A 403 means the API key lacks the policies write scope — re-issue the key with edit:policies.
umb_add_destinations parameters
Param Type Required Default Description
destinationListId string yes The unique numeric id of the destination list (from umb_list_destination_lists).
destinationsJson string yes JSON array of destinations to add; each: {"destination":"badsite.com","comment":"optional"}.
umb_create_destination_list parameters
Param Type Required Default Description
fieldsJson string yes JSON object for the new list. Required: access ("allow"|"block"), isGlobal (bool), name. Optional: bundleTypeId, destinations (array of {destination, comment}).
umb_delete_destination_list parameters
Param Type Required Default Description
destinationListId string yes The unique numeric id of the destination list to delete (from umb_list_destination_lists).
umb_get_destination_list parameters
Param Type Required Default Description
destinationListId string yes The unique numeric id of the destination list (from umb_list_destination_lists).
umb_list_destination_lists parameters
Param Type Required Default Description
limit integer no 100 Records per page (default 100, capped at 1000).
page integer no 1 Page number in the collection (default 1).
umb_list_destinations parameters
Param Type Required Default Description
destinationListId string yes The unique numeric id of the destination list (from umb_list_destination_lists).
limit integer no 100 Records per page (default 100, capped at 1000).
page integer no 1 Page number in the collection (default 1).
umb_remove_destinations parameters
Param Type Required Default Description
destinationListId string yes The unique numeric id of the destination list (from umb_list_destination_lists).
destinationsJson string yes JSON array of destination entry ids to remove (from umb_list_destinations), e.g. [123,456]. Max 500.
umb_update_destination_list parameters
Param Type Required Default Description
destinationListId string yes The unique numeric id of the destination list to update (from umb_list_destination_lists).
fieldsJson string yes JSON object of fields to update. Required: name.

Deployment Policies

Tool Plan Access Description
umb_add_identity_to_policy Pro Write [Cisco Umbrella] Add an identity to a deployment policy. Provide policyId (from umb_list_deployment_policies) and the identity's originId (e.g. a network, roaming computer, virtual appliance, or network device origin id). No request body. Policy changes may take up to 20 minutes to take effect globally. A 403 means the API key lacks the deployments write scope — re-issue the Umbrella API key with edit:deployments.
umb_list_deployment_policies Free Read-only [Cisco Umbrella] List the Umbrella deployment policies. Returns each policy's id, name, and type. Filter by type ("dns" or "web"); when omitted, Umbrella returns DNS policies. Policy ids feed umb_add_identity_to_policy and umb_remove_identity_from_policy. Page-based pagination (page + limit).
umb_remove_identity_from_policy Pro Destructive [Cisco Umbrella] Remove an identity from a deployment policy. Provide policyId (from umb_list_deployment_policies) and the identity's originId. No request body. Policy changes may take up to 20 minutes to take effect globally. A 403 means the API key lacks the deployments write scope — re-issue the Umbrella API key with edit:deployments.
umb_add_identity_to_policy parameters
Param Type Required Default Description
originId string yes The origin id of the identity to add (e.g. a network, roaming computer, virtual appliance, or network device originId).
policyId string yes The numeric id of the policy (from umb_list_deployment_policies).
umb_list_deployment_policies parameters
Param Type Required Default Description
limit integer no 100 Records per page (default 100, capped at 1000).
page integer no 1 Page number in the collection (default 1).
type string no null Policy type to list: "dns" or "web". Omit to return DNS policies (the API default).
umb_remove_identity_from_policy parameters
Param Type Required Default Description
originId string yes The origin id of the identity to remove.
policyId string yes The numeric id of the policy (from umb_list_deployment_policies).

Reports

Tool Plan Access Description
umb_list_identities Free Read-only [Cisco Umbrella] List the identities known to Umbrella reporting (used to interpret and filter other reports). Optional search string and identitytypes (comma-delimited identity types) narrow the results. Page with limit (bounded; the server returns at most 5000 records) + offset. Access Scope: Reports > Utilities > Read-Only.
umb_report_activity Free Read-only [Cisco Umbrella] List all activity events (DNS, proxy, firewall, intrusion) within a time window. The IP activity report is not available here. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.
umb_report_activity_amp_retrospective Free Read-only [Cisco Umbrella] List granular AMP retrospective (post-hoc malware detection) activity events within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with ampdisposition, sha256, and timezone filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.
umb_report_activity_dns Free Read-only [Cisco Umbrella] List DNS activity events within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.
umb_report_activity_firewall Free Read-only [Cisco Umbrella] List firewall activity events within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with categories, verdict, identityids, ip, ports, and ruleid filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.
umb_report_activity_intrusion Free Read-only [Cisco Umbrella] List granular intrusion (IPS) activity events within a time window. Requires the firewall-IPS package; without it the endpoint returns 403 or an empty result set (a data-availability concern, not a connector error). from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with identityids, signatures, signaturelistids, intrusionaction, ip, ports, filternoisydomains, and timezone filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.
umb_report_activity_ip Free Read-only [Cisco Umbrella] List granular IP-layer activity events within a time window. Deprecated in the Umbrella spec (the legacy IP Enforcement Layer) but still served on the current v2 surface. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with identityids, identitytypes, categories, verdict, ip, and ports filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.
umb_report_activity_proxy Free Read-only [Cisco Umbrella] List proxy (secure web gateway) activity events within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Granular Events > Read-Only.
umb_report_summary Free Read-only [Cisco Umbrella] Get an aggregate summary report (request totals with category and threat rollups) for a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. offset paginates. Access Scope: Reports > Aggregations > Read-Only.
umb_report_threat_types Free Read-only [Cisco Umbrella] List the threat types Umbrella recognizes (a reference lookup; no time window or pagination). Use the returned type identifiers to interpret threat-type fields in other reports such as umb_report_top_threats. Access Scope: Reports > Utilities > Read-Only.
umb_report_top_categories Free Read-only [Cisco Umbrella] List the content/security categories that received the most requests in a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, and policycategories filters. offset paginates. Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_destinations_dns Free Read-only [Cisco Umbrella] List the top DNS destinations (domains) by request volume within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_destinations_firewall Free Read-only [Cisco Umbrella] List the top firewall destinations by connection/request volume within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_destinations_ip Free Read-only [Cisco Umbrella] List the top IP-layer (IP enforcement) destinations by request volume within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_destinations_proxy Free Read-only [Cisco Umbrella] List the top proxy destinations by request volume within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_identities Free Read-only [Cisco Umbrella] List the identities that made the most requests within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_ips Free Read-only [Cisco Umbrella] List the top IP addresses by request volume within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, and policycategories filters. Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_threats Free Read-only [Cisco Umbrella] Get the top threats (both DNS and proxy) within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_total_requests Free Read-only [Cisco Umbrella] Get the total count of requests within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Access Scope: Reports > Aggregations > Read-Only.
umb_report_total_requests_dns Free Read-only [Cisco Umbrella] Get the total count of DNS requests within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_total_requests_firewall Free Read-only [Cisco Umbrella] Get the total count of firewall events within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_total_requests_ip Free Read-only [Cisco Umbrella] Get the total count of IP-layer (IP enforcement) requests within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_total_requests_proxy Free Read-only [Cisco Umbrella] Get the total count of proxy requests within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_list_identities parameters
Param Type Required Default Description
identitytypes string no null Optional identity type or comma-delimited list of identity types to filter by.
limit integer no 100 Max records to return (bounded, capped at 1000; server hard cap 5000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
search string no null Optional search string; matches identities whose data contains it.
umb_report_activity parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_activity_amp_retrospective parameters
Param Type Required Default Description
ampdisposition string no null Optional: AMP disposition filter (e.g. clean, malicious, unknown).
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
sha256 string no null Optional: a SHA-256 file hash to filter by.
timezone string no null Optional: timezone for bucketing (e.g. an IANA name or UTC offset).
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_activity_dns parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_activity_firewall parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
ruleid integer no null Optional: the firewall policy rule ID to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_activity_intrusion parameters
Param Type Required Default Description
filternoisydomains string no null Optional: 'true' to filter out noisy domains.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
intrusionaction string no null Optional: intrusion action filter (e.g. would_block, blocked, detected).
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
signaturelistids string no null Optional: a signature-list ID or comma-delimited list to filter by.
signatures string no null Optional: an IPS signature ID or comma-delimited list to filter by.
timezone string no null Optional: timezone for bucketing (e.g. an IANA name or UTC offset).
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_activity_ip parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
identitytypes string no null Optional: an identity type or comma-delimited list of identity types to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_activity_proxy parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_summary parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_top_categories parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_top_destinations_dns parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_top_destinations_firewall parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_top_destinations_ip parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_top_destinations_proxy parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_top_identities parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_top_ips parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_top_threats parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_total_requests parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_total_requests_dns parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_total_requests_firewall parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_total_requests_ip parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_total_requests_proxy parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.

App Discovery

Tool Plan Access Description
umb_appdiscovery_get_app_identities Free Read-only [Cisco Umbrella] List the identities (users/devices) observed using a discovered application. applicationId comes from umb_appdiscovery_list_applications. Page with limit (bounded) + offset. Use this to see who is using a given cloud app. Access Scope: Reports > Read-Only.
umb_appdiscovery_get_app_risk Free Read-only [Cisco Umbrella] Get the risk assessment for a single discovered application: its risk score and the contributing risk attributes used to triage Shadow IT / SaaS exposure. applicationId comes from umb_appdiscovery_list_applications. Access Scope: Reports > Read-Only.
umb_appdiscovery_get_application Free Read-only [Cisco Umbrella] Get a single discovered cloud application by id, including its metadata used to triage Shadow IT / SaaS exposure. applicationId comes from umb_appdiscovery_list_applications. Access Scope: Reports > App Discovery (reports.appDiscovery:read).
umb_appdiscovery_get_protocol Free Read-only [Cisco Umbrella] Get a single application protocol by id. protocolId comes from umb_appdiscovery_list_protocols. Optionally pass date (YYYY-MM-DD) to report as of a specific day. Access Scope: Reports > App Discovery (reports.appDiscovery:read).
umb_appdiscovery_list_application_attributes Free Read-only [Cisco Umbrella] List the attributes (security/compliance/business characteristics) of a discovered application. applicationId comes from umb_appdiscovery_list_applications. Optionally filter by categories (comma-separated). Access Scope: Reports > App Discovery (reports.appDiscovery:read).
umb_appdiscovery_list_application_categories Free Read-only [Cisco Umbrella] List the application categories used to classify discovered cloud apps. Page with limit (1..100) + offset. Access Scope: Reports > App Discovery (reports.appDiscovery:read).
umb_appdiscovery_list_applications Free Read-only [Cisco Umbrella] List cloud applications discovered in your Umbrella traffic (App Discovery / Shadow IT report). Each application carries an id required by umb_appdiscovery_get_app_risk, umb_appdiscovery_get_app_identities, and umb_appdiscovery_update_app_label. Optionally pass date (YYYY-MM-DD) to report as of a specific day; omit for the latest data. Page with limit (bounded) + offset. Access Scope: Reports > Read-Only.
umb_appdiscovery_list_protocol_identities Free Read-only [Cisco Umbrella] List the identities (users/devices) observed using a given application protocol. protocolId comes from umb_appdiscovery_list_protocols. Optionally pass date (YYYY-MM-DD) and sort with sort/order. Page with limit (1..100) + offset. Access Scope: Reports > App Discovery (reports.appDiscovery:read).
umb_appdiscovery_list_protocols Free Read-only [Cisco Umbrella] List cloud application protocols observed in your Umbrella traffic. Optionally filter by identity and sort with sort/order. Page with limit (1..100) + offset. Access Scope: Reports > App Discovery (reports.appDiscovery:read).
umb_appdiscovery_update_app_label Pro Write [Cisco Umbrella] Set the review label / status on a discovered application (for example approve or tag it). applicationId comes from umb_appdiscovery_list_applications. Body (required): label. A 403 means the Umbrella API key lacks the reports write scope — re-issue the key with edit access to App Discovery.
umb_appdiscovery_update_applications Pro Write [Cisco Umbrella] Bulk-set the review label / status on many discovered applications at once (collection-level PATCH — distinct from the single-item umb_appdiscovery_update_app_label). Body (required): label (the review label to apply) and applicationsList (array of 1..1000 application ids). A 403 means the Umbrella API key lacks the App Discovery write scope — re-issue the key with reports.appDiscovery:write.
umb_appdiscovery_get_app_identities parameters
Param Type Required Default Description
applicationId string yes Discovered application id (from umb_appdiscovery_list_applications).
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
umb_appdiscovery_get_app_risk parameters
Param Type Required Default Description
applicationId string yes Discovered application id (from umb_appdiscovery_list_applications).
umb_appdiscovery_get_application parameters
Param Type Required Default Description
applicationId string yes Discovered application id (from umb_appdiscovery_list_applications).
umb_appdiscovery_get_protocol parameters
Param Type Required Default Description
date string no null Optional single date (YYYY-MM-DD) to report as of; defaults to the latest data.
protocolId string yes Protocol id (from umb_appdiscovery_list_protocols).
umb_appdiscovery_list_application_attributes parameters
Param Type Required Default Description
applicationId string yes Discovered application id (from umb_appdiscovery_list_applications).
categories string no null Optional comma-separated attribute categories to filter by.
umb_appdiscovery_list_application_categories parameters
Param Type Required Default Description
limit integer no null Max rows to return (1..100). Omit for the server default.
offset integer no null Row offset for pagination. Omit for 0.
umb_appdiscovery_list_applications parameters
Param Type Required Default Description
date string no null Optional single date (YYYY-MM-DD) to report app discovery as of; defaults to the latest data when omitted.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
umb_appdiscovery_list_protocol_identities parameters
Param Type Required Default Description
date string no null Optional single date (YYYY-MM-DD) to report as of; defaults to the latest data.
limit integer no null Max rows to return (1..100). Omit for the server default.
offset integer no null Row offset for pagination. Omit for 0.
order string no null Optional sort order (asc/desc).
protocolId string yes Protocol id (from umb_appdiscovery_list_protocols).
sort string no null Optional field to sort by.
umb_appdiscovery_list_protocols parameters
Param Type Required Default Description
identity integer no null Optional identity id to scope the protocol listing.
limit integer no null Max rows to return (1..100). Omit for the server default.
offset integer no null Row offset for pagination. Omit for 0.
order string no null Optional sort order (asc/desc).
sort string no null Optional field to sort by.
umb_appdiscovery_update_app_label parameters
Param Type Required Default Description
applicationId string yes Discovered application id to update (from umb_appdiscovery_list_applications).
fieldsJson string yes JSON object for the update. Required: label (the review label/status to apply).
umb_appdiscovery_update_applications parameters
Param Type Required Default Description
fieldsJson string yes JSON object. Required: label (review label/status) and applicationsList (array of 1..1000 discovered application ids to relabel).

API Usage

Tool Plan Access Description
umb_apiusage_keys Free Read-only [Cisco Umbrella] List Umbrella API usage attributed per API key over a date window (which keys made how many calls). from/to are calendar dates in YYYY-MM-DD format, passed verbatim (do not reformat). Use this to attribute consumption to individual keys discovered via umb_list_api_keys. Access Scope: Reports > Read-Only.
umb_apiusage_requests Free Read-only [Cisco Umbrella] List Umbrella API request counts over a date window, broken down by request. from/to are calendar dates in YYYY-MM-DD format, passed verbatim (do not reformat). Companion to umb_apiusage_summary (totals) and umb_apiusage_responses (status-code breakdown). Access Scope: Reports > Read-Only.
umb_apiusage_responses Free Read-only [Cisco Umbrella] List Umbrella API response counts over a date window, broken down by HTTP response/status code. from/to are calendar dates in YYYY-MM-DD format, passed verbatim (do not reformat). Use this to spot elevated error rates (4xx/5xx) in your API traffic. Access Scope: Reports > Read-Only.
umb_apiusage_summary Free Read-only [Cisco Umbrella] Get an aggregate summary of your organization's Umbrella API usage (total request counts and rollups) over a date window. from/to are calendar dates in YYYY-MM-DD format and are passed through verbatim (do not reformat). Use this to gauge overall API consumption before drilling into umb_apiusage_requests, umb_apiusage_responses, or umb_apiusage_keys. Access Scope: Reports > Read-Only.
umb_apiusage_keys parameters
Param Type Required Default Description
from string yes Start date, YYYY-MM-DD (passed verbatim).
to string yes End date, YYYY-MM-DD (passed verbatim).
umb_apiusage_requests parameters
Param Type Required Default Description
from string yes Start date, YYYY-MM-DD (passed verbatim).
to string yes End date, YYYY-MM-DD (passed verbatim).
umb_apiusage_responses parameters
Param Type Required Default Description
from string yes Start date, YYYY-MM-DD (passed verbatim).
to string yes End date, YYYY-MM-DD (passed verbatim).
umb_apiusage_summary parameters
Param Type Required Default Description
from string yes Start date, YYYY-MM-DD (passed verbatim).
to string yes End date, YYYY-MM-DD (passed verbatim).

Investigate

Tool Plan Access Description
umb_investigate_bgp_routes_asn Pro Read-only [Cisco Umbrella] Get the CIDR prefixes and geo information advertised by an Autonomous System Number (ASN). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_bgp_routes_ip Pro Read-only [Cisco Umbrella] Get Autonomous-System information for an IPv4 address (ASN, CIDR, RIR, and owner/description). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_bulk_categorization Pro Read-only [Cisco Umbrella] Provide a list of domains and look up the status, and security and content category IDs for each domain. The domain status is a numerical value determined by the Cisco Security Labs team. Valid status values are: '-1' (malicious), '1' (safe), or '0' (undetermined status). Requires the Umbrella Investigate add-on license; calls return 403/404 without it. Body: {"domains": ["example.com", ...]} (Tier 2/3 only).
umb_investigate_domain_categorization Pro Read-only [Cisco Umbrella] Look up the status, and security and content category IDs for the domain. The domain status is a numerical value determined by the Cisco Security Labs team. Valid status values are: '-1' (malicious), '1' (safe), or '0' (undetermined status). Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_domain_risk_score Pro Read-only [Cisco Umbrella] The Investigate Risk Score is based on an analysis of the lexical characteristics of the domain name and patterns in queries and requests to the domain. The risk score is scaled from 0 to 100 where 100 is the highest risk and 0 represents no risk at all. Periodically, Investigate updates this score based on additional inputs. A domain blocked by Umbrella receives a score of 100. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_domain_security Pro Read-only [Cisco Umbrella] List multiple scores or security features for a domain. You can use the scores or security features to determine relevant data points and build insights on the reputation or security risk posed by the site. No one security information feature is conclusive. Instead, consider these features as part of your security research. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_domain_volume Pro Read-only [Cisco Umbrella] List the query volume for a domain over the last 30 days. If there is no information about the domain, Investigate returns an empty array. As the query takes time to generate, the last two hours may be blank. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_links Pro Read-only [Cisco Umbrella] List domains that co-occur within a small time window of the given domain (the true co-occurrence 'links' endpoint). No pagination. Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_pdns_domain Pro Read-only [Cisco Umbrella] The Passive DNS endpoint provides historical data from the Umbrella resolvers for domains, IPs, and other resource records. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_pdns_ip Pro Read-only [Cisco Umbrella] Get the Resource Record (RR) data for DNS responses, and categorization data, where the answer (or rdata) is the domain(s). Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_pdns_raw Pro Read-only [Cisco Umbrella] Get Passive-DNS Resource Records matching raw rdata (for example TXT record contents). URL-encode the value; wrap TXT strings in quotes. Page with limit + offset (bounded, capped at 1000; default 500). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_pdns_rr_domain Pro Read-only [Cisco Umbrella] Get Passive-DNS Resource Records (RRs) where the answer/rdata is the given domain — the answer-side view, distinct from umb_investigate_pdns_domain which returns query-side RRs on /pdns/name. Page with limit + offset (bounded, capped at 1000; default 500). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_related Pro Read-only [Cisco Umbrella] List the co-occurences for the specified domain. A co-occurrence is when two or more domains are accessed by the same users within a small window of time. Co-occurring domains are not necessarily problematic; legitimate sites co-occur with each other as a part of normal web activity. However, unusual or suspicious co-occurences can provide additional information regarding attacks. To determine co-occurrences for a domain, a small time window of traffic across all of our datacenters is taken. Investigate checks the sites that end users visited before and after the domain was requested in the API call. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_samples Pro Read-only [Cisco Umbrella] Specify a domain, IP, or URL. Use the destination to search for all samples associated with the destination. The default number of items in a response is 10. You can extend the limit. You must have a license for Cisco Secure Malware Analytics to receive the samples data. Cisco Secure Malware Analytics retains checksum samples for one year. You may find that Investigate previously listed a sample related to a destination. If Cisco Secure Malware Analytics no longer contains a sample related to the destination, Investigate does not display the sample in the list of associated samples. An error may occur when the requested destination is not in a valid format, if the requested host is not found in our database, or if there is no data available for the destination that you have requested. CIDR subnets (for example: 10.10.10.0/24) and pattern search is not supported. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_search Pro Read-only [Cisco Umbrella] List the newly seen domains that match a regular expression pattern. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_subdomains Pro Read-only [Cisco Umbrella] List known subdomains of a domain. limit is capped at 100 (default 20); use offsetName (the last subdomain from the previous page) as the pagination cursor. Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_timeline Pro Read-only [Cisco Umbrella] List the historical tagging timeline for a given IP, domain, or URL. Investigate sorts the timeline items in descending order using the timestamp field. Each timeline item includes lists of security category, attack, or threat type associated with the destination. Use the Tagging Timeline endpoint to verify when Umbrella assigned or removed a security category, attack, or threat type. If the current timeline item contains the security category, type of attack, or threat type not found in the previous timeline item, Umbrella updated the current timeline item. If the current timeline item does not contain the security category, attack, or threat type found in the previous timeline item, Umbrella removed the security category, type of attack, or threat type. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_top_million Pro Read-only [Cisco Umbrella] List the most seen domains in Umbrella. You can download the data in a zip file, or use the Investigate API to stream the data into a SIEM. The popularity list contains our most queried domains based on passive DNS usage across our Umbrella global network of more than 180 billion requests per day with many tens of millions of unique active users, in more than 165 countries. The metric does not only consist of browser-based http requests from users but also takes in to account the number of unique client IPs invoking this domain relative to the sum of all requests to all domains. Our popularity ranking reflects the domain's relative internet activity agnostic to the invocation protocols and applications where as site ranking models (such as Alexa) focus on the web activity over port 80 (primarily from browsers). In addition, the Umbrella popularity algorithm also applies data normalization techniques to smooth potential biases that may occur due to sampling of DNS usage data. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_whois Pro Read-only [Cisco Umbrella] Get the WHOIS information for the specified email addresses, nameservers, and domains. You can search by multiple email addresses or multiple nameservers. This documentation outlines the following API endpoints: email (single and multiple), domain record (current and historical), and nameserver (single and multiple). In some instances, WHOIS information can be irregular as there are no standards between domain registrars and large volumes of information can be returned from a query. As such, both the email and nameserver WHOIS endpoints have a limit of 500 results, which you can reduce to a smaller set of results. There is an `offset` parameter that can be leveraged to retrieve the entire set of domain entries for a given email without any limitation. Only the email parameter supports this. You can sort the email parameter by filtering the entries based on the timestamp field. If a domain, email, or nameserver has no known WHOIS information, Investigate returns `HTTP 404`. If a domain, email or nameserver does not exist, Investigate returns `HTTP 404`. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_whois_email Pro Read-only [Cisco Umbrella] List the domains registered by a registrant email address. WHOIS caps at 500 results per request; use offset to page past 500 (email is the one endpoint that pages the full set). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_whois_history Pro Read-only [Cisco Umbrella] List historical WHOIS records for a domain. Default 10 records. Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_whois_nameserver Pro Read-only [Cisco Umbrella] List the domains registered against a SINGLE nameserver (path parameter). WHOIS endpoints cap at 500 results; use offset to page. Distinct from umb_investigate_whois_nameservers (batch query). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_whois_nameservers Pro Read-only [Cisco Umbrella] List the domains registered against a BATCH of nameservers. The required nameServerList is a comma-delimited list of nameserver hostnames. WHOIS endpoints cap at 500 results; use offset to page. Distinct from umb_investigate_whois_nameserver (single, path-param). Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_whois_search Pro Read-only [Cisco Umbrella] Regex-search WHOIS records by field (for example 'nameservers' or 'emails') matching a regular-expression pattern. start is REQUIRED and the search window is at most 30 days. Investigate scope investigate.investigate:read. Requires the Umbrella Investigate add-on license; calls return 403/404 without it.
umb_investigate_bgp_routes_asn parameters
Param Type Required Default Description
asn string yes An Autonomous System Number (ASN), for example '15169'.
umb_investigate_bgp_routes_ip parameters
Param Type Required Default Description
ip string yes An IPv4 address, for example '93.184.216.34'.
umb_investigate_bulk_categorization parameters
Param Type Required Default Description
fieldsJson string yes JSON object with the domains to look up. Required: domains (array of domain strings). Example: {"domains": ["example.com", "foo.net"]}.
showLabels string no null Optional. Pass any value (for example 'true') to include the security and content category labels in the response.
umb_investigate_domain_categorization parameters
Param Type Required Default Description
domain string yes A domain name.
showLabels string no null Optional. Pass any value (for example 'true') to include the security and content category labels in the response.
umb_investigate_domain_risk_score parameters
Param Type Required Default Description
domain string yes A domain name.
umb_investigate_domain_security parameters
Param Type Required Default Description
domain string yes A domain name.
umb_investigate_domain_volume parameters
Param Type Required Default Description
domain string yes A domain name.
match string no null Optional match mode: 'exact', 'component', or 'all' (default 'all').
start string yes Required. Relative (e.g. '-1days', '-2weeks') or absolute epoch-millisecond start within the last 30 days. Filter for data after this time.
stop string no null Optional end of the window: timestamp in milliseconds or relative (e.g. '-1days', 'now'). Max range 30 days.
umb_investigate_links parameters
Param Type Required Default Description
domain string yes A domain name.
umb_investigate_pdns_domain parameters
Param Type Required Default Description
domain string yes A domain name.
includefeatures boolean no null Add feature sections to the response (default false).
limit integer no 500 Records to return (bounded, capped at 1000; upstream max 10,000 across all requests). Default 500.
maxFirstSeen integer no null Only return records with firstSeen <= this epoch value.
maxLastSeen integer no null Only return records with lastSeen <= this epoch value.
minFirstSeen integer no null Only return records with firstSeen >= this epoch value.
minLastSeen integer no null Only return records with lastSeen >= this epoch value.
offset integer no 0 Row offset for pagination. Default 0.
recordType string no null Record type(s), comma-separated. For example: 'A', 'CNAME', 'NS', 'MX'.
requiredCategories string no null Filter to records assigned the given security categories; comma-separated, case-sensitive.
sortCategories string no null Sort records by the given security categories (or 'All'); comma-separated, case-sensitive.
sortby string no null Sort field: 'minTtl', 'maxTtl', 'firstSeen', or 'lastSeen'.
sortorder string no null Sort order: 'asc' or 'desc' (default 'desc').
umb_investigate_pdns_ip parameters
Param Type Required Default Description
includefeatures boolean no null Add feature sections to the response (default false).
ip string yes An IP address, for example: 2620:119:35::35.
limit integer no 500 Records to return (bounded, capped at 1000; upstream max 10,000 across all requests). Default 500.
maxFirstSeen integer no null Only return records with firstSeen <= this epoch value.
maxLastSeen integer no null Only return records with lastSeen <= this epoch value.
minFirstSeen integer no null Only return records with firstSeen >= this epoch value.
minLastSeen integer no null Only return records with lastSeen >= this epoch value.
offset integer no 0 Row offset for pagination. Default 0.
recordType string no null Record type(s), comma-separated. For example: 'A', 'CNAME', 'NS', 'MX'.
requiredCategories string no null Filter to records assigned the given security categories; comma-separated, case-sensitive.
sortCategories string no null Sort records by the given security categories (or 'All'); comma-separated, case-sensitive.
sortby string no null Sort field: 'minTtl', 'maxTtl', 'firstSeen', or 'lastSeen'.
sortorder string no null Sort order: 'asc' or 'desc' (default 'desc').
umb_investigate_pdns_raw parameters
Param Type Required Default Description
anystring string yes A raw rdata value to match, for example a full TXT record string.
includefeatures boolean no null Add feature sections to the response (default false).
limit integer no 500 Records to return (bounded, capped at 1000; upstream max 10,000 across all requests). Default 500.
maxFirstSeen integer no null Only return records with firstSeen <= this epoch value.
maxLastSeen integer no null Only return records with lastSeen <= this epoch value.
minFirstSeen integer no null Only return records with firstSeen >= this epoch value.
minLastSeen integer no null Only return records with lastSeen >= this epoch value.
offset integer no 0 Row offset for pagination. Default 0.
recordType string no null Record type(s), comma-separated. For example: 'A', 'CNAME', 'NS', 'MX', 'TXT'.
requiredCategories string no null Filter to records assigned the given security categories; comma-separated, case-sensitive.
sortCategories string no null Sort records by the given security categories (or 'All'); comma-separated, case-sensitive.
sortby string no null Sort field: 'minTtl', 'maxTtl', 'firstSeen', or 'lastSeen'.
sortorder string no null Sort order: 'asc' or 'desc' (default 'desc').
umb_investigate_pdns_rr_domain parameters
Param Type Required Default Description
domain string yes A domain name.
includefeatures boolean no null Add feature sections to the response (default false).
limit integer no 500 Records to return (bounded, capped at 1000; upstream max 10,000 across all requests). Default 500.
maxFirstSeen integer no null Only return records with firstSeen <= this epoch value.
maxLastSeen integer no null Only return records with lastSeen <= this epoch value.
minFirstSeen integer no null Only return records with firstSeen >= this epoch value.
minLastSeen integer no null Only return records with lastSeen >= this epoch value.
offset integer no 0 Row offset for pagination. Default 0.
recordType string no null Record type(s), comma-separated. For example: 'A', 'CNAME', 'NS', 'MX'.
requiredCategories string no null Filter to records assigned the given security categories; comma-separated, case-sensitive.
sortCategories string no null Sort records by the given security categories (or 'All'); comma-separated, case-sensitive.
sortby string no null Sort field: 'minTtl', 'maxTtl', 'firstSeen', or 'lastSeen'.
sortorder string no null Sort order: 'asc' or 'desc' (default 'desc').
umb_investigate_related parameters
Param Type Required Default Description
domain string yes A domain name.
umb_investigate_samples parameters
Param Type Required Default Description
destination string yes A domain, IP, or URL. For example, 'cisco.com', 195.22.28.196, or 'https://cisco.com'.
limit integer no 10 Items to return (bounded, capped at 1000). Default 10.
offset integer no 0 Row offset for pagination. Default 0.
sortby string no null Sort by 'firstSeen', 'lastSeen', or 'score' (default 'score').
umb_investigate_search parameters
Param Type Required Default Description
expression string yes A standard regular expression pattern search.
includeCategory boolean no null Include security categories in the response (default false).
limit integer no 10 Items to return (bounded, capped at 1000). Default 10.
offset integer no 0 Row offset for pagination. Default 0.
start string yes Required. Relative (e.g. '-1days', '-2weeks') or absolute epoch-millisecond start within the last 30 days. Filter for data after this time.
stop string no null Optional end of the window: timestamp in milliseconds or relative (e.g. '-1days', 'now'). Max range 30 days.
type string no null Search node type: 'URL', 'IP', or 'HOST'.
umb_investigate_subdomains parameters
Param Type Required Default Description
domain string yes A domain name.
limit integer no 20 Subdomains to return (HARD-capped at 100). Default 20.
offsetName string no null Pagination cursor: pass the last subdomain returned by the previous page to fetch the next page.
umb_investigate_timeline parameters
Param Type Required Default Description
name string yes An IP, domain, or URL.
umb_investigate_top_million parameters
Param Type Required Default Description
limit integer no 100 Max domains to return. Always bounded (capped at 1000) to avoid streaming the full one-million list. Default 100.
umb_investigate_whois parameters
Param Type Required Default Description
domain string yes The domain name without wildcards and including the top-level domain (TLD).
umb_investigate_whois_email parameters
Param Type Required Default Description
email string yes A registrant email address.
limit integer no 500 Records to return (WHOIS caps at 500 per request; bounded, capped at 1000). Default 500.
offset integer no 0 Row offset for pagination. Default 0.
sortField string no null Optional field to sort by (for example 'created').
umb_investigate_whois_history parameters
Param Type Required Default Description
domain string yes The domain name without wildcards and including the top-level domain (TLD).
limit integer no 10 Historical records to return (bounded, capped at 1000). Default 10.
umb_investigate_whois_nameserver parameters
Param Type Required Default Description
limit integer no 500 Records to return (WHOIS caps at 500 per request; bounded, capped at 1000). Default 500.
nameserver string yes A single nameserver hostname, for example 'ns1.example.com'.
offset integer no 0 Row offset for pagination. Default 0.
sortField string no null Optional field to sort by (for example 'created').
umb_investigate_whois_nameservers parameters
Param Type Required Default Description
limit integer no 500 Records to return (WHOIS caps at 500 per request; bounded, capped at 1000). Default 500.
nameServerList string yes Required. Comma-delimited list of nameserver hostnames, for example 'ns1.example.com,ns2.example.com'.
offset integer no 0 Row offset for pagination. Default 0.
sortField string no null Optional field to sort by (for example 'created').
umb_investigate_whois_search parameters
Param Type Required Default Description
limit integer no 10 Items to return (bounded, capped at 1000). Default 10.
offset integer no 0 Row offset for pagination. Default 0.
regexExpression string yes A standard regular-expression pattern to match within the chosen field.
searchField string yes The WHOIS field to search, for example 'nameservers' or 'emails'.
sortField string no null Optional field to sort by (for example 'created').
start string yes Required. Relative (e.g. '-1days', '-2weeks') or absolute epoch-millisecond start within the last 30 days. Filter for data after this time.
stop string no null Optional end of the window: timestamp in milliseconds or relative (e.g. '-1days', 'now'). Max range 30 days.

Managed Providers

Tool Plan Access Description
umb_create_managed_customer Pro Write [Cisco Umbrella] Create a customer under the Managed Providers (Multi-Org/MSP) console. Provide a JSON object body — required: customerName (string 1-255) and seats (integer >= 1). Requires a Managed-Provider/MSP-console API key; a 403 means the key lacks the admin.customers:write scope (or is not a provider-tier key) — re-issue the Umbrella API key with that scope.
umb_delete_managed_customer Pro Destructive [Cisco Umbrella] Permanently delete a Managed Providers customer by customerId (from umb_list_managed_customers). This cannot be undone. A 403 means the API key lacks the admin.customers:write scope — re-issue the Umbrella API key with that scope.
umb_get_managed_customer Free Read-only [Cisco Umbrella] Get a single Managed Providers customer by customerId (from umb_list_managed_customers). Returns customerId, customerName, and seats.
umb_list_managed_customers Free Read-only [Cisco Umbrella] List the customers under your Umbrella Managed Providers (Multi-Org/MSP) console. Returns an array of customers, each with customerId, customerName, and seats. Paginated with page + limit (limit max 100). Use umb_get_managed_customer for one customer and the returned customerId with umb_update_managed_customer / umb_delete_managed_customer.
umb_update_managed_customer Pro Write [Cisco Umbrella] Update a Managed Providers customer by customerId (from umb_list_managed_customers). Provide a JSON object body — required: customerName (string 1-255) and seats (integer >= 1); both must be supplied. A 403 means the API key lacks the admin.customers:write scope — re-issue the Umbrella API key with that scope.
umb_create_managed_customer parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: customerName (string 1-255), seats (integer >= 1).
umb_delete_managed_customer parameters
Param Type Required Default Description
customerId string yes The id of the customer to delete (from umb_list_managed_customers).
umb_get_managed_customer parameters
Param Type Required Default Description
customerId string yes The id of the customer (from umb_list_managed_customers).
umb_list_managed_customers parameters
Param Type Required Default Description
limit integer no 100 The number of records to return per page (default 100, max 100).
page integer no 1 The number of the page to return (default 1).
umb_update_managed_customer parameters
Param Type Required Default Description
customerId string yes The id of the customer to update (from umb_list_managed_customers).
fieldsJson string yes JSON object body. Required: customerName (string 1-255), seats (integer >= 1).

Provider Customers

Tool Plan Access Description
umb_create_provider_customer Pro Write [Cisco Umbrella] Create a Service-Provider customer. Provide a JSON object body — required: customerName (1-255), seats (>=1), streetAddress, city, countryCode (2-3), packageId (171/202/246/248/250/252/312), adminEmails (array of email). Optional: streetAddress2, state, zipCode, dealId, ccwDealOwnerEmails, addonRbi ('0'-'3'), addonCdfwL7, addonDlp, licenseType ('term'/'msla'), isTrial. A 403 means the API key lacks admin.customers:write or is not a provider-console key.
umb_delete_provider_customer Pro Destructive [Cisco Umbrella] Permanently delete a Service-Provider customer by customerId. Returns 204 (no content). Cannot be undone. A 403 means the API key lacks admin.customers:write.
umb_get_provider_customer Free Read-only [Cisco Umbrella] Get one Service-Provider customer by customerId (from umb_list_provider_customers). Returns the full customer object. Requires a provider-console key with admin.customers:read.
umb_get_provider_customer_packages Free Read-only [Cisco Umbrella] List the packages available when creating a Service-Provider customer. Returns an array of {id, name, pkgSeatMin, ppovSeatMin}. Use a returned id as packageId in umb_create_provider_customer. Requires a provider-console key with admin.customers:read.
umb_get_provider_customer_subscription Free Read-only [Cisco Umbrella] Get subscription details for a Service-Provider customer by customerId — package, seats, start/end dates, trial lifecycle, access-request state. (createdAt/modifiedAt here are epoch-seconds integers, e.g. 1594557263; note the top-level Customer schema instead uses ISO-8601 strings for these fields.) Requires a provider-console key with admin.customers:read.
umb_list_provider_customers Free Read-only [Cisco Umbrella] List the customers under your Umbrella Service-Provider/MSSP console. Returns an array of customers (customerId, customerName, packageName/packageId, seats, address, adminEmails, addons). Paginated with page + limit (max 100). Requires a provider-console key with admin.customers:read. A 403/404 means the API key lacks that scope or is not a provider-console key.
umb_update_provider_customer Pro Write [Cisco Umbrella] Update a Service-Provider customer by customerId (full replace). JSON body — required: customerName, seats, streetAddress, city, countryCode, packageId, adminEmails. Optional: streetAddress2, state, zipCode, dealId, ccwDealOwnerEmails. Note: the update body does NOT accept licenseType/isTrial/addonRbi/addonCdfwL7/addonDlp (response-only fields). A 403 means the API key lacks admin.customers:write.
umb_create_provider_customer parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: customerName, seats, streetAddress, city, countryCode, packageId, adminEmails. Optional: streetAddress2, state, zipCode, dealId, ccwDealOwnerEmails, addonRbi, addonCdfwL7, addonDlp, licenseType, isTrial.
umb_delete_provider_customer parameters
Param Type Required Default Description
customerId string yes The id of the customer to delete (from umb_list_provider_customers).
umb_get_provider_customer parameters
Param Type Required Default Description
customerId string yes The id of the customer (from umb_list_provider_customers).
umb_get_provider_customer_subscription parameters
Param Type Required Default Description
customerId string yes The id of the customer (from umb_list_provider_customers).
umb_list_provider_customers parameters
Param Type Required Default Description
limit integer no 100 The number of records to return per page (default 100, max 100).
page integer no 1 The number of the page to return (default 1).
umb_update_provider_customer parameters
Param Type Required Default Description
customerId string yes The id of the customer to update (from umb_list_provider_customers).
fieldsJson string yes JSON object body (full replace). Required: customerName, seats, streetAddress, city, countryCode, packageId, adminEmails. Optional: streetAddress2, state, zipCode, dealId, ccwDealOwnerEmails.

Provider Trials & Access

Tool Plan Access Description
umb_convert_provider_customer_trial Pro Destructive [Cisco Umbrella] Irreversibly convert a trial to a paying customer by customerId. Provide a JSON object body — required: packageId (one of 246/248/250/252). Returns . This changes billing state and cannot be undone. Requires admin.customers:write on a provider-console key. (Vendor example shows 107 but the enum is [246,248,250,252] — send an enum value.)
umb_create_provider_access_request Pro Write [Cisco Umbrella] Request delegated access to a customer's Umbrella org by customerId. No request body (built from the path and provider identity). Returns the AccessRequest object. Requires admin.customers:write on a provider-console key.
umb_extend_provider_customer_trial Pro Write [Cisco Umbrella] Extend a customer's trial by customerId. Provide a JSON object body — trialExtensionDays (must be 7 or 14). Returns the full customer object. Requires admin.customers:write on a provider-console key.
umb_get_provider_access_request Free Read-only [Cisco Umbrella] Get a delegated-access request by customerId and accessRequestId. Returns the request object (id, organizationId, state = approved/denied/pending, organizationName, timestamps). Requires a provider-console key with admin.customers:read.
umb_get_provider_customer_trial_strength Free Read-only [Cisco Umbrella] Get a trial customer's engagement strength by customerId — customerLoggedIn, lastLoginDate, identitiesCreated, hasTraffic, trialStrength (Low/Medium/High/-). Requires a provider-console key with admin.customers:read.
umb_update_provider_access_request Pro Write [Cisco Umbrella] Advance a delegated-access request's state by customerId and accessRequestId. No request body — the transition is a server-side action driven by the path, so a repeat call is not guaranteed to be a no-op. Returns the updated AccessRequest. Requires admin.customers:write on a provider-console key.
umb_convert_provider_customer_trial parameters
Param Type Required Default Description
customerId string yes The id of the customer (from umb_list_provider_customers).
fieldsJson string yes JSON object body. Required: packageId (one of 246/248/250/252).
umb_create_provider_access_request parameters
Param Type Required Default Description
customerId string yes The id of the customer (from umb_list_provider_customers).
umb_extend_provider_customer_trial parameters
Param Type Required Default Description
customerId string yes The id of the customer (from umb_list_provider_customers).
fieldsJson string yes JSON object body. Required: trialExtensionDays (7 or 14).
umb_get_provider_access_request parameters
Param Type Required Default Description
accessRequestId string yes The id of the access request (from umb_create_provider_access_request).
customerId string yes The id of the customer (from umb_list_provider_customers).
umb_get_provider_customer_trial_strength parameters
Param Type Required Default Description
customerId string yes The id of the customer (from umb_list_provider_customers).
umb_update_provider_access_request parameters
Param Type Required Default Description
accessRequestId string yes The id of the access request to advance (from umb_create_provider_access_request).
customerId string yes The id of the customer (from umb_list_provider_customers).

Provider Deals & Organizations

Tool Plan Access Description
umb_get_provider_customer_deal Free Read-only [Cisco Umbrella] Get a customer deal by dealId. Required query ccoId (integer — the CCO id of the querying user). Returns an array of CustomerDeal objects (Cisco returns array shape even for get-by-id). Requires a provider-console key with admin.customerDeals:read; a 403 means the key lacks that scope or is not a provider-console key.
umb_list_provider_customer_addresses Free Read-only [Cisco Umbrella] List Service-Provider customer addresses. Paginated with page + limit (max 100). Returns an array of {accountId, accountSiteId, mappedCrPartyId, organizationName, address fields}. Requires a provider-console key with admin.customerSearch:read; a 403 means the key lacks that scope.
umb_list_provider_organizations Free Read-only [Cisco Umbrella] List the organizations visible to a provider-org member. Required query email (a member of the provider org). Optional page/offset/limit (max 100). Returns an array of {organizationId, organizationName, mspOrganizationId, organizationTypeId, ...}. A 404 means the email was not found. Requires a provider-console key with admin.organizations:read.
umb_reset_provider_customer_passwords Pro Destructive [Cisco Umbrella] Force a password reset for named admin accounts in a child (customer) org by customerId. Provide a JSON object body — required: adminEmails (array of the child-org user emails to reset). This irreversibly invalidates those users' current passwords and triggers a reset flow. 200 returns an empty body. Requires a parent (provider) org token with admin.passwordreset:write; a 403 means the key lacks that scope or is not a provider-console key.
umb_update_provider_customer_deal Pro Write [Cisco Umbrella] Update a customer deal by dealId (full replace). Provide a JSON object body — required: ccoid (integer), customerId (integer); optional: quoteId (integer), majorLineItems (array of {objectId, sourceAppRefId}). NB casing: the write op carries ccoid in the body (the read uses ccoId in the query). Requires admin.customerDeals:write; a 403 means the key lacks that scope or is not a provider-console key.
umb_get_provider_customer_deal parameters
Param Type Required Default Description
ccoId integer yes Required. The CCO id (integer) of the querying user.
dealId string yes The id of the customer deal.
umb_list_provider_customer_addresses parameters
Param Type Required Default Description
limit integer no 100 The number of records to return per page (default 100, max 100).
page integer no 1 The number of the page to return (default 1).
umb_list_provider_organizations parameters
Param Type Required Default Description
email string yes Required. The email of a member of the provider org whose visible organizations to list.
limit integer no 100 The number of records to return per page (default 100, max 100).
offset integer no 0 The number of records to skip (default 0).
page integer no 1 The number of the page to return (default 1).
umb_reset_provider_customer_passwords parameters
Param Type Required Default Description
customerId string yes The id of the customer (child) org whose admins to reset (from umb_list_provider_customers).
fieldsJson string yes JSON object body. Required: adminEmails (array of the child-org user emails to reset).
umb_update_provider_customer_deal parameters
Param Type Required Default Description
dealId string yes The id of the customer deal to update.
fieldsJson string yes JSON object body. Required: ccoid (integer), customerId (integer). Optional: quoteId (integer), majorLineItems (array of {objectId, sourceAppRefId}).

Provider Branding

Tool Plan Access Description
umb_create_provider_cname Pro Write [Cisco Umbrella] Create a console CNAME. Provide a JSON object body — required: cname (string, e.g. "example.com"). Returns 200 with the created object. A 403 means the API key lacks admin.config:write or is not a provider-console key.
umb_create_provider_contact Pro Write [Cisco Umbrella] Create a console contact. Provide a JSON object body — required: contactType (billing/blockfeedback/report/serviceupdate/support/distributor), emailAddress. Optional: primaryContact (yes/no), name/address/phone fields, nested settings.organization{name,email}. A 403 means the API key lacks admin.config:write or is not a provider-console key.
umb_create_provider_logo Pro Write [Cisco Umbrella] Upload a branding logo (multipart/form-data). Params — all required: imageBase64 (the image file, base64-encoded), imageUrl, token (64 chars), enabled (bool), brandingTypeId (int). Returns the logo object. A 403 means the API key lacks admin.config:write or is not a provider-console key.
umb_delete_provider_cname Pro Destructive [Cisco Umbrella] Delete a console CNAME by cnameId. Returns 204 (no content). Cannot be undone. Requires admin.config:write on a provider-console key.
umb_delete_provider_contact Pro Destructive [Cisco Umbrella] Delete a console contact by contactId. Returns 204 (no content). Cannot be undone. Requires admin.config:write on a provider-console key.
umb_delete_provider_logo Pro Destructive [Cisco Umbrella] Delete a logo by logoId. Returns 204 (no content). Cannot be undone. Requires admin.config:write on a provider-console key.
umb_get_provider_cname Free Read-only [Cisco Umbrella] Get one console CNAME by cnameId (from umb_list_provider_cnames). Requires admin.config:read.
umb_get_provider_contact Free Read-only [Cisco Umbrella] Get one console contact by contactId (from umb_list_provider_contacts). Requires admin.config:read.
umb_get_provider_logo Free Read-only [Cisco Umbrella] Get one logo's metadata by logoId (JSON, not binary). Requires admin.config:read.
umb_list_provider_cnames Free Read-only [Cisco Umbrella] List the console CNAMEs. Returns an array of {cnameId, cname, organizationId}. Requires a provider-console key with admin.config:read.
umb_list_provider_contacts Free Read-only [Cisco Umbrella] List console contacts (billing/support/report/…). Returns an array; output flattens orgName/distributorVisibility to top level. Requires admin.config:read.
umb_list_provider_logos Free Read-only [Cisco Umbrella] List logo metadata (id, imageUrl, imageKey, token, enabled, brandingTypeId, timestamps) — JSON, not image bytes. Requires admin.config:read.
umb_update_provider_cname Pro Write [Cisco Umbrella] Update (full replace) a console CNAME by cnameId. Provide a JSON object body — required: cname. Requires admin.config:write on a provider-console key.
umb_update_provider_contact Pro Write [Cisco Umbrella] Update (full replace) a console contact by contactId. Provide a JSON object body with the same schema as umb_create_provider_contact. Requires admin.config:write on a provider-console key.
umb_update_provider_logo Pro Write [Cisco Umbrella] Replace a logo by logoId (multipart/form-data, full replace). Params — all required: imageBase64, imageUrl, token, enabled, brandingTypeId. Requires admin.config:write on a provider-console key.
umb_create_provider_cname parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: cname (e.g. "example.com").
umb_create_provider_contact parameters
Param Type Required Default Description
fieldsJson string yes JSON object body. Required: contactType (billing/blockfeedback/report/serviceupdate/support/distributor), emailAddress. Optional: primaryContact, name/address/phone fields, settings.organization{name,email}.
umb_create_provider_logo parameters
Param Type Required Default Description
brandingTypeId integer yes The branding type id.
enabled boolean yes Whether the logo is enabled.
imageBase64 string yes The image file, base64-encoded.
imageUrl string yes The image URL.
token string yes The branding token (64 chars).
umb_delete_provider_cname parameters
Param Type Required Default Description
cnameId string yes The id of the CNAME to delete (from umb_list_provider_cnames).
umb_delete_provider_contact parameters
Param Type Required Default Description
contactId string yes The id of the contact to delete (from umb_list_provider_contacts).
umb_delete_provider_logo parameters
Param Type Required Default Description
logoId string yes The id of the logo to delete (from umb_list_provider_logos).
umb_get_provider_cname parameters
Param Type Required Default Description
cnameId string yes The id of the CNAME (from umb_list_provider_cnames).
umb_get_provider_contact parameters
Param Type Required Default Description
contactId string yes The id of the contact (from umb_list_provider_contacts).
umb_get_provider_logo parameters
Param Type Required Default Description
logoId string yes The id of the logo (from umb_list_provider_logos).
umb_update_provider_cname parameters
Param Type Required Default Description
cnameId string yes The id of the CNAME to update (from umb_list_provider_cnames).
fieldsJson string yes JSON object body. Required: cname.
umb_update_provider_contact parameters
Param Type Required Default Description
contactId string yes The id of the contact to update (from umb_list_provider_contacts).
fieldsJson string yes JSON object body. Same schema as umb_create_provider_contact (required: contactType, emailAddress).
umb_update_provider_logo parameters
Param Type Required Default Description
brandingTypeId integer yes The branding type id.
enabled boolean yes Whether the logo is enabled.
imageBase64 string yes The image file, base64-encoded.
imageUrl string yes The image URL.
logoId string yes The id of the logo to replace (from umb_list_provider_logos).
token string yes The branding token (64 chars).

Provider Reporting

Tool Plan Access Description
umb_create_provider_security_report Pro Write [Cisco Umbrella] Enqueue generation of a customer security report by customerId (Service-Provider/MSSP console). No request body; returns 200 with header.status='pending', task='enqueue-task'. Poll results with umb_get_provider_security_report. Restriction: only tokens issued for a Partner Proof-of-Value (PPoV) parent organization are authorized — a non-PPoV key will 4xx. Requires reports.customers:write on a provider-console key.
umb_get_provider_console_data Free Read-only [Cisco Umbrella] Get the Service-Provider/MSSP console subscription summary — packageName, seatsTotal/seatsUsed, customerCount, status, rebillAt, expiresAt. No parameters (scoped by the provider-console token). Requires reports.customers:read on a provider-console key.
umb_get_provider_security_report Free Read-only [Cisco Umbrella] Fetch/poll the generated customer security report (Service-Provider/MSSP console). isReportReady (bool) is the readiness flag — poll this after umb_create_provider_security_report. No parameters (scoped by the provider-console token). JSON output only (the vendor outputFormat=csv variant is intentionally not exposed). Requires reports.customers:read on a provider-console key.
umb_provider_report_categories Free Read-only [Cisco Umbrella] List the content categories available for provider (Service-Provider/MSSP console) reporting. Returns {data:[{id, legacyid, label, type, integration, deprecated}]} — use a returned id in the categories/policycategories filters of the other provider report tools. Vendor scope for this op: reports.utilities:read. A 403 means the API key lacks that scope or is not a provider-console key.
umb_provider_report_category_requests_by_org Free Read-only [Cisco Umbrella] Per-managed-customer content-category breakdown across all managed customer organizations (Service-Provider/MSSP console) over a from/to window. from/to accept an epoch-millisecond timestamp or a relative string ('-1days'/'now'), passed verbatim. Optional threats/threattypes/filternoisydomains. limit is bounded (capped at 1000). Requires reports.customers:read on a provider-console key.
umb_provider_report_deployments Free Read-only [Cisco Umbrella] Deployment status per managed customer organization over a from/to window (Service-Provider/MSSP console). from/to accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now') and are passed through verbatim. Optionally narrow with threats and threattypes (comma-delimited). Requires a provider-console key with reports.customers:read.
umb_provider_report_requests_by_category Free Read-only [Cisco Umbrella] Request totals by content category across all managed customer organizations (Service-Provider/MSSP console) over a from/to window. from/to accept an epoch-millisecond timestamp or a relative string ('-1days'/'now'), passed verbatim. Optional threats/threattypes/filternoisydomains. limit is bounded (capped at 1000). Requires reports.customers:read on a provider-console key.
umb_provider_report_requests_by_destination Free Read-only [Cisco Umbrella] Top destinations across all managed customer organizations (Service-Provider/MSSP console) over a from/to window. from/to accept an epoch-millisecond timestamp or a relative string ('-1days'/'now'), passed verbatim. Optional threats/threattypes/filternoisydomains. limit is bounded (capped at 1000). Requires reports.customers:read on a provider-console key.
umb_provider_report_requests_by_hour Free Read-only [Cisco Umbrella] Request totals bucketed by hour across all managed customer organizations (Service-Provider/MSSP console). from/to accept an epoch-millisecond timestamp or a relative string ('-1days'/'now'), passed verbatim. Page with limit (bounded, capped at 1000) + offset. Optional filters: domains, urls, categories, policycategories, ip, identityids, identitytypes, applicationid, verdict, sha256, threats, threattypes, datalosspreventionstate (e.g. 'blocked'), filternoisydomains. Requires reports.customers:read on a provider-console key.
umb_provider_report_requests_by_org Free Read-only [Cisco Umbrella] Per-managed-customer request totals ({organization, counts:{total, totalblocked}}) over a from/to window (Service-Provider/MSSP console). from/to accept an epoch-millisecond timestamp or a relative string ('-1days'/'now'), passed verbatim. Optional threats/threattypes/filternoisydomains. limit is bounded (capped at 1000). Requires reports.customers:read on a provider-console key.
umb_provider_report_requests_by_timerange Free Read-only [Cisco Umbrella] Request totals bucketed by a timerange granularity across all managed customer organizations (Service-Provider/MSSP console). The granularity is set by the timerange parameter (minute/hour/day; sent as a request header, defaults to hour). from/to accept an epoch-millisecond timestamp or a relative string ('-1days'/'now'), passed verbatim. Page with limit (bounded, capped at 1000) + offset. Same optional filters as requests-by-hour minus sha256. Requires reports.customers:read on a provider-console key.
umb_create_provider_security_report parameters
Param Type Required Default Description
customerId string yes The id of the customer (from umb_list_provider_customers) to generate the security report for.
umb_provider_report_category_requests_by_org parameters
Param Type Required Default Description
filternoisydomains boolean no null Optional: set true to filter out noisy domains.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
threats string no null Optional: a threat or comma-delimited list of threats to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_provider_report_deployments parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
threats string no null Optional: a threat or comma-delimited list of threats to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_provider_report_requests_by_category parameters
Param Type Required Default Description
filternoisydomains boolean no null Optional: set true to filter out noisy domains.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
threats string no null Optional: a threat or comma-delimited list of threats to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_provider_report_requests_by_destination parameters
Param Type Required Default Description
filternoisydomains boolean no null Optional: set true to filter out noisy domains.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
threats string no null Optional: a threat or comma-delimited list of threats to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_provider_report_requests_by_hour parameters
Param Type Required Default Description
applicationid string no null Optional: an application ID to filter by.
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
datalosspreventionstate string no null Optional: data-loss-prevention state filter (e.g. 'blocked').
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
filternoisydomains boolean no null Optional: set true to filter out noisy domains.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs to filter by.
identitytypes string no null Optional: an identity type or comma-delimited list of identity types to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
sha256 string no null Optional: a SHA-256 file hash to filter by.
threats string no null Optional: a threat or comma-delimited list of threats to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
urls string no null Optional: a URL or comma-delimited list of URLs to filter by.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_provider_report_requests_by_org parameters
Param Type Required Default Description
filternoisydomains boolean no null Optional: set true to filter out noisy domains.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
threats string no null Optional: a threat or comma-delimited list of threats to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_provider_report_requests_by_timerange parameters
Param Type Required Default Description
applicationid string no null Optional: an application ID to filter by.
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
datalosspreventionstate string no null Optional: data-loss-prevention state filter (e.g. 'blocked').
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
filternoisydomains boolean no null Optional: set true to filter out noisy domains.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs to filter by.
identitytypes string no null Optional: an identity type or comma-delimited list of identity types to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
threats string no null Optional: a threat or comma-delimited list of threats to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
timerange string no null Optional: bucket granularity — minute, hour, or day. Sent as a request header; defaults to hour.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
urls string no null Optional: a URL or comma-delimited list of URLs to filter by.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.

Report Aggregations

Tool Plan Access Description
umb_report_bandwidth_by_hour Free Read-only [Cisco Umbrella] Get bandwidth usage bucketed by hour within a time window (secure web gateway / proxy traffic only). from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_bandwidth_by_timerange Free Read-only [Cisco Umbrella] Get bandwidth usage bucketed by a configurable time range within a window (secure web gateway / proxy traffic only). from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. The bucket size is set by the timerange parameter (minute, hour, or day; default hour). Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_categories_by_hour Free Read-only [Cisco Umbrella] Get request counts by hour and content/security category across all traffic types within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_categories_by_hour_by_type Free Read-only [Cisco Umbrella] Get request counts by hour and content/security category for a specific traffic type within a time window. type must be one of dns, proxy, ip. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_categories_by_timerange Free Read-only [Cisco Umbrella] Get request counts by content/security category bucketed by a configurable time range across all traffic types within a window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. The bucket size is set by the timerange parameter (minute, hour, or day; default hour). Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_categories_by_timerange_by_type Free Read-only [Cisco Umbrella] Get request counts by content/security category bucketed by a configurable time range for a specific traffic type within a window. type must be one of dns, proxy, ip. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. The bucket size is set by the timerange parameter (minute, hour, or day; default hour). Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_requests_by_hour Free Read-only [Cisco Umbrella] Get request counts bucketed by hour across all traffic types within a time window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_requests_by_hour_by_type Free Read-only [Cisco Umbrella] Get request counts bucketed by hour for a specific traffic type within a time window. type must be one of dns, proxy, firewall, intrusion, ip. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_requests_by_timerange Free Read-only [Cisco Umbrella] Get request counts bucketed by a configurable time range across all traffic types within a window. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. The bucket size is set by the timerange parameter (minute, hour, or day; default hour). Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_requests_by_timerange_by_type Free Read-only [Cisco Umbrella] Get request counts bucketed by a configurable time range for a specific traffic type within a window. type must be one of dns, proxy, firewall, intrusion, ip. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. The bucket size is set by the timerange parameter (minute, hour, or day; default hour). Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_categories_by_type Free Read-only [Cisco Umbrella] List the top content/security categories by request volume for a specific traffic type within a time window, in descending order. type must be one of dns, proxy, ip. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset (required by this endpoint; no limit — default 0 is always sent). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_destinations Free Read-only [Cisco Umbrella] List the top destinations across all traffic types by request volume within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded); offset is required by this endpoint (default 0 is always sent). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_dns_query_types Free Read-only [Cisco Umbrella] List the top DNS query types (A, AAAA, MX, TXT, …) by request volume within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_eventtypes Free Read-only [Cisco Umbrella] Get aggregated event-type counts within a time window (this endpoint takes no limit/offset). from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_files Free Read-only [Cisco Umbrella] List the top files seen in proxy/SWG traffic by request volume within a time window, in descending order (proxy/SWG only). from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Optionally narrow with filename, sha256, verdict, ampdisposition, and identityids filters. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_identities_by_type Free Read-only [Cisco Umbrella] List the identities that made the most requests for a specific traffic type within a time window, in descending order. type must be one of dns, proxy, firewall, ip. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_ips_internal Free Read-only [Cisco Umbrella] List the top internal IP addresses by request volume within a time window (this endpoint takes no limit/offset). from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_threat_types Free Read-only [Cisco Umbrella] List the top threat types across all traffic by volume within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_threat_types_by_type Free Read-only [Cisco Umbrella] List the top threat types for a specific traffic type within a time window, in descending order. type must be one of dns, proxy. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_threats_by_type Free Read-only [Cisco Umbrella] List the top threats for a specific traffic type within a time window, in descending order. type must be one of dns, proxy. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_top_urls Free Read-only [Cisco Umbrella] List the top URLs (SWG/proxy traffic) by request volume within a time window, in descending order. from/to accept an epoch-millisecond timestamp or a relative string (for example '-7days' or 'now') and are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded); offset is required by this endpoint (default 0 is always sent). Access Scope: Reports > Aggregations > Read-Only.
umb_report_bandwidth_by_hour parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_bandwidth_by_timerange parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
timerange string no null Optional bucket size. One of: minute, hour, day. When omitted the server defaults to hour.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_categories_by_hour parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_categories_by_hour_by_type parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
type string yes Traffic type. One of: dns, proxy, ip.
umb_report_categories_by_timerange parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
timerange string no null Optional bucket size. One of: minute, hour, day. When omitted the server defaults to hour.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_categories_by_timerange_by_type parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
timerange string no null Optional bucket size. One of: minute, hour, day. When omitted the server defaults to hour.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
type string yes Traffic type. One of: dns, proxy, ip.
umb_report_requests_by_hour parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_requests_by_hour_by_type parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
type string yes Traffic type. One of: dns, proxy, firewall, intrusion, ip.
umb_report_requests_by_timerange parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
timerange string no null Optional bucket size. One of: minute, hour, day. When omitted the server defaults to hour.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_requests_by_timerange_by_type parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
timerange string no null Optional bucket size. One of: minute, hour, day. When omitted the server defaults to hour.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
type string yes Traffic type. One of: dns, proxy, firewall, intrusion, ip.
umb_report_top_categories_by_type parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
offset integer no 0 Row offset for pagination (required by this endpoint). Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
type string yes Traffic type. One of: dns, proxy, ip.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_top_destinations parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination (required by this endpoint). Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_top_dns_query_types parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_top_eventtypes parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_top_files parameters
Param Type Required Default Description
ampdisposition string no null Optional: AMP disposition filter (e.g. clean, malicious, unknown).
filename string no null Optional: a file name to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
sha256 string no null Optional: a SHA-256 file hash to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_top_identities_by_type parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
type string yes Traffic type. One of: dns, proxy, firewall, ip.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_top_ips_internal parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_top_threat_types parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_top_threat_types_by_type parameters
Param Type Required Default Description
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
type string yes Traffic type. One of: dns, proxy.
umb_report_top_threats_by_type parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
type string yes Traffic type. One of: dns, proxy.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_top_urls parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes Start of the window: epoch-millisecond timestamp or relative string (e.g. '-7days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination (required by this endpoint). Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.

Report Summaries

Tool Plan Access Description
umb_report_applications Free Read-only [Cisco Umbrella] List the applications known to Umbrella reporting (a reference lookup used to interpret application fields in other reports). Optionally pass an application name/substring to filter. This is the reporting-utility listing, distinct from the App Discovery applications surface. Access Scope: Reports > Utilities > Read-Only.
umb_report_categories Free Read-only [Cisco Umbrella] List all content and security categories Umbrella recognizes (a reference lookup; no time window, no parameters, no pagination). Use the returned category IDs to interpret and filter other reports. Access Scope: Reports > Utilities > Read-Only.
umb_report_deployment_status Free Read-only [Cisco Umbrella] Get deployment-status counts (how many requests came from fully vs partially protected identities) within a time window. from/to are REQUIRED and accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now'); both are passed through verbatim. Optionally filter by threats and threattypes, and set the timezone. No pagination (no limit/offset). Access Scope: Reports > Aggregations > Read-Only.
umb_report_get_identities_by_ids Free Read-only [Cisco Umbrella] Resolve a batch of identity IDs to their labels/metadata. This is a POST-as-read: it sends a request body but does not modify anything. Body: {"identityids": [123, 456, ...]}. Page the resolved results with limit (bounded). Access Scope: Reports > Utilities > Read-Only.
umb_report_get_identity Free Read-only [Cisco Umbrella] Get a single identity (label and metadata) by its identity ID. Access Scope: Reports > Utilities > Read-Only.
umb_report_get_threat_name Free Read-only [Cisco Umbrella] Get a single threat name by its threat-name ID (for example 'WannaCry'). A reference lookup; no time window or pagination. Access Scope: Reports > Utilities > Read-Only.
umb_report_get_threat_type Free Read-only [Cisco Umbrella] Get a single threat type by its threat-type ID (for example 'Ransomware'). A reference lookup; no time window or pagination. Access Scope: Reports > Utilities > Read-Only.
umb_report_identity_distribution Free Read-only [Cisco Umbrella] Get the distribution of requests across identity types within a time window (all traffic types). from/to are REQUIRED and accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now'); both are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_identity_distribution_by_type Free Read-only [Cisco Umbrella] Get the distribution of requests across identity types within a time window, for a single traffic type (dns or proxy). from/to are REQUIRED and accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now'); both are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_summaries_by_category Free Read-only [Cisco Umbrella] Get per-category summaries (request totals with allowed/blocked rollups per content/security category) within a time window (all traffic types). from/to are REQUIRED and accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now'); both are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_summaries_by_category_by_type Free Read-only [Cisco Umbrella] Get per-category summaries within a time window, for a single traffic type (dns, proxy, or ip). from/to are REQUIRED and accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now'); both are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_summaries_by_destination Free Read-only [Cisco Umbrella] Get per-destination summaries (request totals with allowed/blocked rollups per destination) within a time window (all traffic types). from/to are REQUIRED and accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now'); both are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_summaries_by_destination_by_type Free Read-only [Cisco Umbrella] Get per-destination summaries within a time window, for a single traffic type (dns or proxy). from/to are REQUIRED and accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now'); both are passed through verbatim. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_summaries_by_rule_intrusion Free Read-only [Cisco Umbrella] Get intrusion (IPS) signature-list summaries within a time window — counts per signature list / rule. Requires the firewall-IPS package (returns 403/empty without it). from/to are REQUIRED and accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now'); both are passed through verbatim. Optionally narrow results with signatures, signaturelistids, ip, identityids, identitytypes, intrusionaction, and ports filters. Page with offset + limit (bounded). Access Scope: Reports > Summaries By Rule > Read-Only.
umb_report_summary_by_type Free Read-only [Cisco Umbrella] Get a single aggregate summary object (request totals with allowed/blocked rollups) for a single traffic type (dns, proxy, firewall, or ip) within a time window. from/to are REQUIRED and accept an epoch-millisecond timestamp or a relative string (for example '-1days' or 'now'); both are passed through verbatim. Optionally narrow results with domains, categories, threattypes, verdict, identityids, ip, ports, and policycategories filters. Page with offset + limit (bounded). Access Scope: Reports > Aggregations > Read-Only.
umb_report_threat_names Free Read-only [Cisco Umbrella] List all threat names Umbrella recognizes (a reference lookup; no time window, no parameters, no pagination). Use the returned names to interpret threat-name fields in other reports. Access Scope: Reports > Utilities > Read-Only.
umb_report_applications parameters
Param Type Required Default Description
application string no null Optional: an application name or substring to filter the listing by.
umb_report_deployment_status parameters
Param Type Required Default Description
from string yes REQUIRED. Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
threats string no null Optional: a threat or comma-delimited list of threats to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
timezone string no null Optional: an IANA timezone name (e.g. 'America/New_York') for bucketing.
to string yes REQUIRED. End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_get_identities_by_ids parameters
Param Type Required Default Description
fieldsJson string yes JSON object with the identity IDs to resolve. Required: identityids (array of identity IDs). Example: {"identityids": [123, 456]}.
limit integer no 100 Max resolved records to return (bounded, capped at 1000). Default 100.
umb_report_get_identity parameters
Param Type Required Default Description
identityId string yes The identity ID to fetch (from umb_list_identities).
umb_report_get_threat_name parameters
Param Type Required Default Description
threatNameId string yes The threat-name ID to fetch (e.g. 'WannaCry'; see umb_report_threat_names).
umb_report_get_threat_type parameters
Param Type Required Default Description
threatTypeId string yes The threat-type ID to fetch (e.g. 'Ransomware'; see umb_report_threat_types).
umb_report_identity_distribution parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes REQUIRED. Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes REQUIRED. End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_identity_distribution_by_type parameters
Param Type Required Default Description
from string yes REQUIRED. Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes REQUIRED. End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
type string yes Traffic type to report on: dns or proxy.
umb_report_summaries_by_category parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes REQUIRED. Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes REQUIRED. End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_summaries_by_category_by_type parameters
Param Type Required Default Description
from string yes REQUIRED. Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes REQUIRED. End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
type string yes Traffic type to report on: dns, proxy, or ip.
umb_report_summaries_by_destination parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes REQUIRED. Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes REQUIRED. End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.
umb_report_summaries_by_destination_by_type parameters
Param Type Required Default Description
from string yes REQUIRED. Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
to string yes REQUIRED. End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
type string yes Traffic type to report on: dns or proxy.
umb_report_summaries_by_rule_intrusion parameters
Param Type Required Default Description
from string yes REQUIRED. Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
identitytypes string no null Optional: an identity type or comma-delimited list of identity types to filter by.
intrusionaction string no null Optional: intrusion action filter — one or a comma-delimited list of would_block, blocked, detected.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
signaturelistids string no null Optional: a signature-list ID or comma-delimited list of signature-list IDs to filter by.
signatures string no null Optional: a signature ID or comma-delimited list of intrusion signature IDs to filter by.
to string yes REQUIRED. End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
umb_report_summary_by_type parameters
Param Type Required Default Description
categories string no null Optional: a category ID or comma-delimited list of category IDs to filter by.
domains string no null Optional: a domain or comma-delimited list of domains to filter by.
from string yes REQUIRED. Start of the window: epoch-millisecond timestamp or relative string (e.g. '-1days'). Passed verbatim.
identityids string no null Optional: an identity ID or comma-delimited list of identity IDs (from umb_list_identities) to filter by.
ip string no null Optional: an IP address to filter by.
limit integer no 100 Max rows to return (bounded, capped at 1000). Default 100.
offset integer no 0 Row offset for pagination. Default 0.
policycategories string no null Optional: a category ID or comma-delimited list of policy-triggering category IDs to filter by.
ports string no null Optional: a port or comma-delimited list of ports to filter by.
threattypes string no null Optional: a threat type or comma-delimited list of threat types to filter by.
to string yes REQUIRED. End of the window: epoch-millisecond timestamp or 'now'. Passed verbatim.
type string yes Traffic type to summarize: dns, proxy, firewall, or ip.
verdict string no null Optional: verdict filter — one or a comma-delimited list of allowed, blocked, proxied.

Application Lists

Tool Plan Access Description
umb_create_application_list Pro Write [Cisco Umbrella] Create an application list. Body (required): applicationListName (string), isDefault (bool), applicationIds (array of application ids to include). A 403 means the Umbrella API key lacks the policies write scope — re-issue the key with policies.applicationlists:write.
umb_delete_application_list Pro Destructive [Cisco Umbrella] Permanently delete an application list. Any policy referencing it loses that application grouping — this cannot be undone. applicationListId comes from umb_list_application_lists. Access Scope: Policies (policies.applicationlists:write).
umb_get_application_list Free Read-only [Cisco Umbrella] Get a single application list by id, including its member application ids. applicationListId comes from umb_list_application_lists. Access Scope: Policies (policies.applicationlists:read).
umb_get_applications_usage Free Read-only [Cisco Umbrella] Report where a set of applications is in use across policies. Both query params are REQUIRED: attributeName (e.g. 'umbrella.destination.application_ids') and attributeValue (comma-separated application ids). Access Scope: Policies (policies.applicationlists:read).
umb_list_application_lists Free Read-only [Cisco Umbrella] List all application lists in the organization (named groupings of cloud applications used by web/SWG policies). Returns {count, result[]}; each entry carries an applicationListId used by umb_get_application_list, umb_update_application_list, and umb_delete_application_list. Access Scope: Policies (policies.applicationlists:read).
umb_update_application_list Pro Write [Cisco Umbrella] Replace an application list (full PUT, not a partial PATCH). applicationListId comes from umb_list_application_lists. Body (required, same shape as create): applicationListName, isDefault, applicationIds. A 403 means the Umbrella API key lacks the policies write scope — re-issue the key with policies.applicationlists:write.
umb_create_application_list parameters
Param Type Required Default Description
fieldsJson string yes JSON object. Required: applicationListName, isDefault, applicationIds (array of application ids).
umb_delete_application_list parameters
Param Type Required Default Description
applicationListId string yes Application list id to delete (from umb_list_application_lists).
umb_get_application_list parameters
Param Type Required Default Description
applicationListId string yes Application list id (from umb_list_application_lists).
umb_get_applications_usage parameters
Param Type Required Default Description
attributeName string yes Required. Attribute name to query, e.g. 'umbrella.destination.application_ids'.
attributeValue string yes Required. Attribute value — a comma-separated list of application ids.
umb_update_application_list parameters
Param Type Required Default Description
applicationListId string yes Application list id to update (from umb_list_application_lists).
fieldsJson string yes JSON object (same shape as create). Required: applicationListName, isDefault, applicationIds (array).

SWG Device Settings

Tool Plan Access Description
umb_list_swg_device_settings Free Read-only [Cisco Umbrella] List the per-device SWG (Secure Web Gateway) override settings for specific roaming devices. Provide fieldsJson: a JSON object with originIds (a JSON array of device origin ids, at most 100 per call), e.g. {"originIds":[123456,123457]}. Returns each device's current SWG override. This read is sent as a POST with a request body (POST-as-read). Vendor scope: Deployments > Devices > SWG (deployments.devices.swg:read).
umb_remove_swg_device_setting Pro Destructive [Cisco Umbrella] Remove the per-device SWG (Secure Web Gateway) override on specific roaming devices, reverting each device to the organization-level SWG setting. Provide fieldsJson: a JSON object with originIds (a JSON array of device origin ids, at most 100 per call), e.g. {"originIds":[123456,123457]}. Vendor scope: Deployments > Devices > SWG (deployments.devices.swg:write). A 403 means the API key lacks the deployments write scope — re-issue the key with edit:deployments.
umb_set_swg_device_setting Pro Write [Cisco Umbrella] Override the SWG (Secure Web Gateway) enablement on specific roaming devices, overriding the organization-level setting. Provide fieldsJson: a JSON object with value ("1" to enable, "0" to disable) and originIds (a JSON array of device origin ids, at most 100 per call), e.g. {"value":"1","originIds":[123456,123457]}. Vendor scope: Deployments > Devices > SWG (deployments.devices.swg:write). A 403 means the API key lacks the deployments write scope — re-issue the Umbrella API key with edit:deployments.
umb_list_swg_device_settings parameters
Param Type Required Default Description
fieldsJson string yes JSON object. Required: originIds (JSON array of up to 100 device origin ids).
umb_remove_swg_device_setting parameters
Param Type Required Default Description
fieldsJson string yes JSON object. Required: originIds (JSON array of up to 100 device origin ids).
umb_set_swg_device_setting parameters
Param Type Required Default Description
fieldsJson string yes JSON object. Required: value ("1" enable | "0" disable), originIds (JSON array of up to 100 device origin ids).