Welcome to the new Golem Cloud Docs! 👋
Get Workers API

Get Workers API

The get workers API allows you to get information about the workers for given component.

To use the get workers API, first make sure to add the contents of the wit/deps folders from https://github.com/golemcloud/golem-wit (opens in a new tab) to your own wit/deps folder. You can then interact with the get workers interface from your own code in whatever language you are working in.

Our WIT file will look like this:

package golem:it;

interface api {
  use golem:api/host@0.2.0.{
  get-idle-workers: func(component-id: component-id) -> list<worker-metadata>;

world workers {
  import golem:api/host@0.2.0;

  export api;

Now that we have our interface we are ready to implement it. Let's take a look at how we would do that:

mod bindings;
use crate::bindings::exports::golem::it::api::Guest;
use crate::bindings::golem::api::host::*;
struct Component;
impl Guest for Component {
    fn get_idle_workers(
        component_id: ComponentId
    ) -> Vec<WorkerMetadata> {
            "Get idle workers of component: {component_id:?}"
        let filter = Some(WorkerAnyFilter {
            filters: vec![WorkerAllFilter {
                filters: vec![WorkerPropertyFilter::Status(WorkerStatusFilter {
                    comparator: FilterComparator::Equal,
                    value: WorkerStatus::Idle,
        let mut workers: Vec<WorkerMetadata> = Vec::new();
        let getter = GetWorkers::new(component_id, filter.as_ref(), true);
        loop {
            match getter.get_next() {
                Some(values) => {
                None => break,

The get-idle-workers function is using the get-workers golem-wit resource, which is defined as follows:

resource get-workers {
  constructor(component-id: component-id, filter: option<worker-any-filter>, precise: bool);

  get-next: func() -> option<list<worker-metadata>>;

With get-workers resource, our component is able to get workers of provided component with matching filters, get-next function will return next chunk of workers, or will return none if there is no more workers.

Filter types

worker-name-filterstring-filter-comparatorName of worker, rust example: WorkerNameFilter { comparator: StringFilterComparator::Equal, value: "worker-name".to_string() }
worker-version-filterfilter-comparatorVersion of worker, rust example: WorkerVersionFilter { comparator: FilterComparator::Greater, value: 0 }
worker-status-filterfilter-comparatorStatus of worker, rust example: WorkerStatusFilter { comparator: FilterComparator::Equal, value: WorkerStatus::Idle }
worker-env-filterstring-filter-comparatorEnvironment variable of worker, rust example: WorkerEnvFilter { name: "var1".to_string(), comparator: StringFilterComparator::Equal, value: "val".to_string() }
worker-create-at-filterfilter-comparatorCreation time of worker, rust example: WorkerCreatedAtFilter { comparator: FilterComparator::Greater, value: 1713207300140 }
worker-any-filterOr filter combinator
worker-all-filterAnd filter combinator


  • string-filter-comparator: equal, not-equal, like, not-like
  • filter-comparator: equal, not-equal, greater-equal, greater, less-equal, less