Using Agent Search Parameters in Bulk Operations | Medplum

On this page

Several of the Medplum Agent operations can act on more than one agent at a time. Instead of targeting a single agent by ID, you invoke the operation against the Agent type endpoint and use Agent search parameters to select which agents the operation should run against.

This page collects common "recipes" for selecting agents with search parameters, so you don't have to look up the same query patterns on each individual operation page.

Operations that support search parameters

The following operations accept Agent search parameters to select their operation targets when invoked against the type-level endpoint ([base]/Agent/$operation):

In each case, the operation is run against every agent matched by the query, and the response is a Bundle of Parameters, one entry per matched agent.

Single vs. multiple agents

The $status operation is single-agent only and does not accept search parameters. To query the status of multiple agents at once, use $bulk-status.

Available `Agent` search parameters

The Agent resource defines the following resource-specific search parameters:

name — the agent's name (string search; matches by prefix)
identifier — an Agent.identifier (token search)
status — the agent's status, e.g. active or off (token search)

In addition, the standard "global" search parameters apply, including:

_id — the agent's logical ID
_tag — a tag on Agent.meta.tag
_lastUpdated — when the agent resource was last updated
_count and _offset — for paging through large result sets

Default and maximum page size

When _count is omitted, these operations act on at most the default page size of 20 agents — they do not automatically run against every matching agent. The maximum allowed _count is 100; requesting a larger _count returns an OperationOutcome error. To operate on more agents than fit on a single page, use _count and _offset to page through the results.

Recipes

The recipes below use $bulk-status as an example, but the same query patterns work for any operation that supports search parameters — just swap in the operation you want to run ($fetch-logs, $stats, $upgrade, etc.).

All active agents

Select agents whose status is active — the most common multi-agent query. Note that without a _count, this acts on at most the default page of 20 agents:

medplum get 'Agent/$bulk-status?status=active'

Agents matching a name prefix

Select all agents whose name starts with a given prefix:

medplum get 'Agent/$bulk-status?name=Production+Agent'

Agents with a given tag

Select all agents tagged with a particular value:

medplum get 'Agent/$bulk-status?_tag=Group+A'

Combining search parameters

Search parameters can be combined to narrow the selection. For example, all active agents in Group A:

medplum get 'Agent/$bulk-status?status=active&_tag=Group+A'

Paging through agents

When operating on a large number of agents, page through them in batches using _count and _offset:

medplum get 'Agent/$bulk-status?_count=50&_offset=0'
medplum get 'Agent/$bulk-status?_count=50&_offset=50'

Targeting a single agent by name or identifier

In addition to selecting an agent by its logical ID ([base]/Agent/[id]/$operation), you can target a single agent against the type-level endpoint by using a search parameter that you expect to be unique:

medplum get 'Agent/$bulk-status?name=Test+Agent+1'
medplum get 'Agent/$fetch-logs?identifier=agent-007'

These are conventions, not guarantees

Using name or identifier to target a "single" agent is only a convention. Neither name nor identifier is required to be unique across agents in a project.