> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search
> Find projects, studies, simulations, models, optimizations, and cells across your organization with a single API call
Search lets you quickly find resources across your organization without
querying each endpoint individually. A single query returns matching
projects, studies, simulations, models, parameterized models, optimizations,
optimization templates, experiment templates, pipelines, cell specifications,
cell instances, cell measurements, materials, cyclers, and channels.
Search is available both through the REST API and from the global search bar
in Ionworks Studio. Open the search bar from the top of any page in Studio,
or call the `/search` endpoint directly from your own scripts and tools.
## What you can search
| Resource type | Examples of what's matched |
| ---------------------- | --------------------------------------------- |
| Projects | Project names and descriptions |
| Studies | Study names within projects you can access |
| Simulations | Simulation names and metadata |
| Models | Model names and descriptions |
| Parameterized models | Parameterized model names |
| Optimizations | Optimization run names |
| Optimization templates | Built-in and custom template names |
| Experiment templates | Built-in and custom protocol templates |
| Pipelines | Pipeline names and descriptions |
| Cell specifications | Cell names, chemistries, and identifiers |
| Cell instances | Serial numbers and instance identifiers |
| Cell measurements | Measurement names and metadata |
| Materials | Anode, cathode, and electrolyte materials |
| Cyclers | Cycler names and descriptions |
| Channels | Channel names and identifiers within a cycler |
Search matches against names, descriptions, and other identifying fields for
each resource type. Results are scoped to your current organization and
respect your project-level permissions — you only see resources you have
access to.
## Using search via the API
Search is available at the `/search` endpoint. See the
[API Reference](/api-reference) for the full request and response schema.
A typical request specifies the query string and returns matches grouped by
resource type:
```bash theme={null}
curl -X GET "https://api.ionworks.com/search?q=NMC622" \
-H "Authorization: Bearer $IONWORKS_API_KEY"
```
Results are filtered to the resources your API key has access to.
### Query parameters
| Parameter | Type | Default | Description |
| -------------- | ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q` | string | — | Search query. Minimum 2 characters. Required. |
| `limit` | int | `25` | Maximum results to return in this page (1–100). |
| `offset` | int | `0` | Number of results to skip before this page. Use with `limit` to paginate. |
| `per_type` | int | `5` | Maximum results to return per entity type (1–20) before pagination is applied. |
| `entity_types` | string (repeatable) | — | Restrict results to these entity types. Omit to search all types. Unknown values are ignored. |
| `project_id` | string | — | Narrow the project-filtered entities (studies, pipelines, optimizations) to one project. All other entity types (cell specifications, cell instances, cell measurements, materials, templates) are returned regardless of this value — even though cell specifications now belong to a project, search does not filter them by it. |
### Response shape
The response includes the matching `results`, the original `query`, and the
pagination fields `total`, `limit`, and `offset` so clients can render page
navigation:
```json theme={null}
{
"query": "NMC622",
"results": [ /* ... */ ],
"total": 42,
"limit": 25,
"offset": 0
}
```
`total` reflects all fetched matches across queried entity types, bounded by
`per_type` × the number of entity types searched. It is therefore a fetch-level
ceiling rather than the true number of matching records in the database — with
the default `per_type=5` and 14 entity types it can never exceed 70, even when
thousands of records match. Don't rely on `total / limit` to compute an exact
page count for large result sets.
### Pagination and filtering example
Fetch the second page of cell and material matches, returning up to 10 per
type. The `project_id` here narrows only the project-filtered types (studies,
pipelines, optimizations); cell and material results are returned regardless:
```bash theme={null}
curl -G "https://api.ionworks.com/search" \
-H "Authorization: Bearer $IONWORKS_API_KEY" \
--data-urlencode "q=NMC622" \
--data-urlencode "limit=20" \
--data-urlencode "offset=20" \
--data-urlencode "per_type=10" \
--data-urlencode "entity_types=cell" \
--data-urlencode "entity_types=material" \
--data-urlencode "project_id=proj_01HXYZ..."
```
### Result fields
Each result includes an `entity_type`, `id`, `name`, and `project_id` (when
the resource lives inside a project). Results for nested resources also
include a `parent_id` that points to the containing resource — for example,
the `parent_id` of a `cell_instance` result is an ID pointing to the cell
specification it belongs to, and the `parent_id` of a `channel` result is an
ID pointing to its cycler. You can use `parent_id` to navigate or query the
parent directly.
### Finding cyclers and channels
To restrict a query to hardware only, pass `entity_types=cycler` and
`entity_types=channel`. Both are project-scoped, so `project_id` narrows the
results to a single project when provided:
```bash theme={null}
curl -G "https://api.ionworks.com/search" \
-H "Authorization: Bearer $IONWORKS_API_KEY" \
--data-urlencode "q=maccor" \
--data-urlencode "entity_types=cycler" \
--data-urlencode "entity_types=channel"
```
Each `channel` result carries the `cycler_id` of its parent cycler in
`parent_id`, which you can use to look up the cycler directly.
Search is useful when you remember a partial name (for example, a cell
chemistry, a customer name, or a protocol keyword) but don't know which
project or study contains it.
Search uses server-side full-text indexing, so queries return fast even as
your organization accumulates many resources. Indexes are maintained
automatically — there is nothing to configure.