---
title: "Search data labels across all spreadsheets uploaded to an account"
method: POST
path: "/v1/workbooks/search/labels"
tags: ["workbooks"]
---

# Search data labels across all spreadsheets uploaded to an account

`POST /v1/workbooks/search/labels`

## Request body

- LabelSearchRequest — Define the data labels you want to search for, along with the number and quality of results to return.
  - `query` string, required
  - `max_results` integer, nullable — Maximum number of workbooks to return results for
  - `max_labels` integer, nullable — Maximum number of labels to return per workbook

## Response `200`

Successful Response

- LabelSearchResponse — The results of a spreadsheet data label search.
  - `results` WorkbookResult[], required
    - `workbook_id` string, required — UUID for the workbook
    - `creator_id` string, required — UUID for the user that uploaded the workbook. This will always be the UUID of the account linked to the API key used in the request.
    - `filename` string, required — Original filename of the workbook
    - `description` string, required — Generated description summarising the contents of the workbook
    - `latest_version` integer, required — Most recent version number of the workbook
    - `thumbnail_url` string, required — Absolute URL for a thumbnail of the workbook's first sheet
    - `labels` LabelResult[], required — Array of labels within the workbook that match the search query
      - `for` string, required — Cell reference or range that contains the labelled data
      - `text` string, required — Text content of the label
      - `value` string, required — The labelled data value(s). If a range of data is labelled, this will be a stringified JSON array
      - `score` number, nullable — Relevance ranking of the workbook in relation to the search results (higher is better)
    - `score` number, nullable — Relevance ranking of the workbook in relation to the search results (higher is better)

## Other responses

- `400` — Error returned when you make a bad request
- `403` — Error returned when you don't have permission to query a workbook
- `429` — Error returned when you exceed your API rate limit

---

[API](https://skmtc.net/grid-is/apis/grid-api.md) · [All operations](https://skmtc.net/grid-is/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/grid-is/grid-api/revisions/2f55490ab23d/schema)