Skip to content

Add API endpoint warnings #47841

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
spalmesano0 wants to merge 2 commits into
base: main
Choose a base branch
from
+7 −2
Draft

Add API endpoint warnings #47841

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
63964af
Add notes to use `exclude_software`
spalmesano0 Jun 18, 2026
2bbce47
Add warning about using `query` and setting `device_mapping=true`
spalmesano0 Jun 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions docs/REST API/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3200,6 +3200,8 @@ the `software` table.

> `populate_software` returns a lot of data per host when set, and drastically more data when set to `true` on Fleet Premium. If you need vulnerability details for a large number of hosts, consider setting `populate_software` to `without_vulnerability_details` and pulling vulnerability details from the [Get vulnerability](#get-vulnerability) endpoint, as this returns details once per vulnerability rather than once per vulnerability per host.

> Searching with `query` and setting `device_mapping=true` are each expensive, and combining them is more so. If you're hitting this endpoint often the best practice is to reduce how frequently you call it to prevent overloading the Fleet server.

@noahtalerman noahtalerman Jun 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> Searching with `query` and setting `device_mapping=true` are each expensive, and combining them is more so. If you're hitting this endpoint often the best practice is to reduce how frequently you call it to prevent overloading the Fleet server.
> Searching with `query` and setting `device_mapping=true` are each expensive, and combining them is more so. If you're running a scheduled job that hits this endpoint, the best practice is to run it no more than once per hour to avoid overloading the Fleet server.

@spalmesano0 I tweaked the language to add a specific suggestion but totally guessed on once per hour...is it right? Can we give a faster best practice? 30 minutes?

Also, I think let's move this performance warning to the top of the section: https://github.com/fleetdm/fleet/pull/47841/changes#r3437435430

@spalmesano0 spalmesano0 Jun 18, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rfairburn said this was originally triggered after hitting it with ~10 req/sec. I'd defer to him on the infrastructure recommendation, though I imagine once every few minutes wouldn't be bad.

@noahtalerman I think the placement of the Get host by Fleet Desktop token warning right under the endpoint title may have been a mistake (probably made by me!), as the warnings for List hosts and List software versions were already under parameters.
With that in mind, do you still want me to move the warnings for the four endpoints here and List software versions near the title?


If `software_title_id` is specified, an additional top-level key `"software_title"` is returned with the software title object corresponding to the `software_title_id`. See [List software](#list-software) response payload for details about this object.

If `software_version_id` is specified, an additional top-level key `"software"` is returned with the software object corresponding to the `software_version_id`. See [List software versions](#list-software-versions) response payload for details about this object.
Expand Down Expand Up @@ -3676,6 +3678,8 @@ Returns the information of the specified host.
| exclude_software | boolean | query | If `true`, the response will not include a list of installed software for the host. |
| exclude_fleet_maintained_policies | boolean | query | If `true`, will omit Fleet-maintained policies from the policies list. |

> If you're hitting this endpoint often (e.g. every hour) for a large number of hosts (e.g. 1k+) the best practice is to set the `exclude_software` to `true` to prevent overloading the Fleet server.

@noahtalerman noahtalerman Jun 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@spalmesano0 I think let's move this to the top of this section, right below the "Get host" header. That way we're consistent w/ the "Get host by Fleet Desktop token":

Image


#### Example

`GET /api/v1/fleet/hosts/121`
Expand Down Expand Up @@ -3982,6 +3986,7 @@ If `hostname` is specified when there is more than one host with the same hostna
| exclude_software | boolean | query | If `true`, the response will not include a list of installed software for the host. |
| exclude_fleet_maintained_policies | boolean | query | If `true`, will omit Fleet-maintained policies from the policies list. |

> If you're hitting this endpoint often (e.g. every hour) for a large number of hosts (e.g. 1k+) the best practice is to set the `exclude_software` to `true` to prevent overloading the Fleet server.

#### Example

Expand Down Expand Up @@ -4202,8 +4207,6 @@ If `hostname` is specified when there is more than one host with the same hostna

### Get host by Fleet Desktop token

> If you're hitting this endpoint often (e.g. every hour) for a large number of hosts (e.g. 1k+) the best practice is to set the `exclude_software` to `true` to prevent overloading the Fleet server.

Returns a subset of information about the host specified by `token`. To get all information about a host, use the ["Get host"](#get-host) endpoint.

This is the API route used by the **My device** page in Fleet Desktop to display information about the host to the end user.
Expand All @@ -4219,6 +4222,8 @@ This endpoint doesn't require API token authentication. Authentication on macOS,
| token | string | path | The host's [Fleet Desktop token](https://fleetdm.com/guides/fleet-desktop#secure-fleet-desktop). For macOS, Windows, and Linux, this is a random UUID that rotates hourly. For iOS and iPadOS, this is the host's hardware UUID. |
| exclude_software | boolean | query | If `true`, the response will not include a list of installed software for the host. |

> If you're hitting this endpoint often (e.g. every hour) for a large number of hosts (e.g. 1k+) the best practice is to set the `exclude_software` to `true` to prevent overloading the Fleet server.

#### Request headers

This endpoint accepts the `X-Client-Cert-Serial` header for authentication in addition to token authentication.
Expand Down
Loading