---
layout: api
page_title: Search - HTTP API
description: The /search endpoint is used to search for Nomad objects
---

# Search HTTP API

## Prefix Searching

The `/search` endpoint returns matches for a given prefix and context, where a
context can be jobs, allocations, evaluations, nodes, node pools, deployments,
plugins, namespaces, or volumes. When using Nomad Enterprise, the allowed
contexts include quotas. Additionally, a prefix can be searched for within
every context.

| Method | Path         | Produces           |
| ------ | ------------ | ------------------ |
| `POST` | `/v1/search` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required                                     |
| ---------------- | ------------------------------------------------ |
| `NO`             | `node:read, node_pool:read, namespace:read-jobs` |

When ACLs are enabled, requests must have a token valid for `node:read`,
`node_pool:read`, or `namespace:read-jobs` roles. If the token is only valid
for a portion of these capabilities, then results will include results
including only data readable with the given token.

### Parameters

- `Prefix` `(string: <required>)` - Specifies the identifier against which
  matches will be found. For example, if the given prefix were "a", potential
  matches might be "abcd", or "aabb".
- `Context` `(string: <required>)` - Defines the scope in which a search for a
  prefix operates. Contexts can be: "jobs", "evals", "allocs", "nodes",
  "node_pools", "deployment", "plugins", "volumes" or "all", where "all" means
  every context will be searched.

### Sample Payload (for all contexts)

```json
{
  "Prefix": "abc",
  "Context": "all"
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search
```

### Sample Response

```json
{
  "Matches": {
    "allocs": null,
    "deployment": null,
    "evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"],
    "jobs": ["abcde"],
    "nodes": null,
    "plugins": null,
    "volumes": null
  },
  "Truncations": {
    "allocs": "false",
    "deployment": "false",
    "evals": "false",
    "jobs": "false",
    "nodes": "false",
    "plugins": "false",
    "volumes": "false"
  }
}
```

#### Field Reference

- `Matches` - A map of contexts to matching arrays of identifiers.

- `Truncations` - Search results are capped at 20; if more matches were found for a particular context, it will be `true`.

### Sample Payload (for a specific context)

```json
{
  "Prefix": "abc",
  "Context": "evals"
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search
```

### Sample Response

```json
{
  "Matches": {
    "evals": ["abc2fdc0-e1fd-2536-67d8-43af8ca798ac"]
  },
  "Truncations": {
    "evals": "false"
  }
}
```

## Fuzzy Searching

The `/search/fuzzy` endpoint returns partial substring matches for a given
search term and context, where a context can be jobs, allocations, nodes, node
pools, plugins, or namespaces. Additionally, fuzzy searching can be done across
all contexts. For better control over the performance implications of fuzzy
searching on Nomad servers, aspects of fuzzy searching can be tuned through
the <code>[search]</code> block in Nomad agent config.

Fuzzy search results are ordered starting with closest matching terms. Items of
a name that exactly matches the search term are listed first.

| Method | Path               | Produces           |
| ------ | ------------------ | ------------------ |
| `POST` | `/v1/search/fuzzy` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required                                                                |
| ---------------- | --------------------------------------------------------------------------- |
| `NO`             | `node:read, node_pool:read, namespace:read-jobs, namespace:csi-list-plugin` |

When ACLs are enabled, requests must have a token valid for `node:read`,
`node_pool:read`, `plugin:read`, or `namespace:read-jobs` roles. If the token
is only valid for a portion of these capabilities, then results will include
results including only data readable with the given token.

### Parameters

- `Text` `(string: <required>)` - Specifies the identifier against which
  matches will be found. For example, if the given text were "py", potential
  fuzzy matches might be "python", "spying", or "happy".

- `Context` `(string: <required>)` - Defines the scope in which a search for a
  prefix operates. Contexts can be: "jobs", "allocs", "nodes", "node_pools",
  "plugins", or "all", where "all" means every context will be searched. When
  "all" is selected, additional prefix matches will be included for the
  "deployments", "evals", and "volumes" types. When searching in the "jobs"
  context, results that fuzzy match "groups", "services", "tasks", "images",
  "commands", and "classes" are also included in the results.

### Scope

Fuzzy match results are accompanied with a `Scope` field which is used to uniquely
identify the matched object, in a way that the Nomad API can be queried again for
additional information. The data provided by scope varies depending on the type
of matched object, described below.

### Sample Payload (for jobs)

```json
{
  "Text": "py",
  "Context": "jobs"
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search/fuzzy
```

### Sample Response

```json
{
  "Index": 90,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "services": [
      {
        "ID": "python-logger",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app",
          "my-python-task"
        ]
      },
      {
        "ID": "super-spy-service",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app"
        ]
      }
    ],
    "tasks": [
      {
        "ID": "my-python-task",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app"
        ]
      }
    ],
    "images": [
      {
        "ID": "python:3",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app",
          "my-python-task"
        ]
      }
    ],
    "jobs": [
      {
        "ID": "example-python",
        "Scope": [
          "default"
        ]
      }
    ],
    "groups": [
      {
        "ID": "my-spy-app",
        "Scope": [
          "default",
          "example-python"
        ]
      }
    ]
  },
  "Truncations": {
    "jobs": false
  }
}
```

#### Scope (jobs)

- `Scope[0]` : Namespace
- `Scope[1]` : Job ID

#### Scope (groups)

- `Scope[0]` : Namespace
- `Scope[1]` : Job ID

#### Scope (tasks)

- `Scope[0]` : Namespace
- `Scope[1]` : Job ID
- `Scope[2]` : Group

#### Scope (group services)

- `Scope[0]` : Namespace
- `Scope[1]` : Group

#### Scope (task services)

- `Scope[0]` : Namespace
- `Scope[1]` : Job ID
- `Scope[2]` : Group
- `Scope[3]` : Task

#### Scope (commands/images/classes)

- `Scope[0]` : Namespace
- `Scope[1]` : Job ID
- `Scope[2]` : Group
- `Scope[3]` : Task

### Sample Payload (for nodes)

```json
{
  "Text": "lab",
  "Context": "nodes"
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search/fuzzy
```

### Sample Response

```json
{
  "Index": 9,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "nodes": [
      {
        "ID": "nomad-lab1",
        "Scope": [
          "c48cd39f-dfe1-9cc0-9c62-617d199854be"
        ]
      }
    ]
  },
  "Truncations": {
    "nodes": false
  }
}
```

##### Scope (nodes)

- `Scope[0]` : Node ID

### Sample Payload (for node pools)

```json
{
  "Text": "lab",
  "Context": "node_pools"
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search/fuzzy
```

### Sample Response

```json
{
  "Index": 9,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "node_pools": [
      {
        "ID": "dev-lab1",
        "Scope": [
          "dev-lab1"
        ]
      }
    ]
  },
  "Truncations": {
    "nodes": false
  }
}
```

##### Scope (node pools)

- `Scope[0]` : Node Pool Name

### Sample Payload (for allocs)

```json
{
   "Text":"py",
   "Context":"allocs"
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search/fuzzy
```

### Sample Response

```json
{
  "Index": 136,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "allocs": [
      {
        "ID": "example-python.my-spy-app[0]",
        "Scope": [
          "default",
          "0fb703d1-ba4d-116f-13aa-27f31f046858"
        ]
      }
    ]
  },
  "Truncations": {
    "allocs": false
  }
}
```

#### Scope (allocs)

- `Scope[0]` : Namespace
- `Scope[1]` : Alloc ID


### Sample Payload (for plugins)

```json
{
  "Text": "aws",
  "Context": "plugins"
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search/fuzzy
```

### Sample Response

```json
{
  "Index": 0,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "plugins": [
      {
        "ID": "aws-efs0"
      }
    ]
  },
  "Truncations": {
    "plugins": false
  }
}
```

### Sample Payload (for all)

```json
{
  "Index": 260,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "services": [
      {
        "ID": "python-logger",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app",
          "my-python-task"
        ]
      },
      {
        "ID": "super-spy-service",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app"
        ]
      }
    ],
    "tasks": [
      {
        "ID": "my-python-task",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app"
        ]
      }
    ],
    "jobs": [
      {
        "ID": "example-python",
        "Scope": [
          "default"
        ]
      }
    ],
    "evals": [],
    "scaling_policy": [],
    "groups": [
      {
        "ID": "my-spy-app",
        "Scope": [
          "default",
          "example-python"
        ]
      }
    ],
    "images": [
      {
        "ID": "python:3",
        "Scope": [
          "default",
          "example-python",
          "my-spy-app",
          "my-python-task"
        ]
      }
    ],
    "plugins": [
      {
        "ID": "aws-spy-plugin"
      }
    ],
    "deployment": [],
    "volumes": [],
    "allocs": [
      {
        "ID": "example-python.my-spy-app[0]",
        "Scope": [
          "default",
          "48608246-4c28-0446-f3d1-c67e3bc650ad"
        ]
      }
    ]
  },
  "Truncations": {
    "deployment": false,
    "volumes": false,
    "plugins": false,
    "namespaces": false,
    "scaling_policy": false,
    "evals": false,
    "allocs": false,
    "jobs": false,
    "nodes": false
  }
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search/fuzzy
```

### Prefix matching when fuzzy searching

If the search Context is `all` when fuzzy searching, the object types that are
identified only with UUIDs are also concurrently prefix-searched. Those types include
deployments, evals, volumes, and quotas (Enterprise).

### Sample Payload (prefix match)

```json
{
   "Text":"cc",
   "Context":"all"
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/search/fuzzy
```

### Sample Result
```json
{
  "Index": 267,
  "KnownLeader": true,
  "LastContact": 0,
  "Matches": {
    "scaling_policy": [],
    "evals": [],
    "deployment": [
      {
        "ID": "cc786388-e071-31ec-5821-b829839f9681"
      }
    ],
    "volumes": []
  },
  "Truncations": {
    "deployment": false,
    "volumes": false,
    "plugins": false,
    "namespaces": false,
    "scaling_policy": false,
    "evals": false,
    "allocs": false,
    "jobs": false,
    "nodes": false
  }
}
```

[search]: /nomad/docs/configuration/search
