---
title: "Search Asset"
method: POST
path: "/search/asset/{asset_id}/run"
tags: ["Search"]
---

# Search Asset

`POST /search/asset/{asset_id}/run`

## Request

- Base URL: `https://api.aspect.inc`
- URL: `https://api.aspect.inc/search/asset/{asset_id}/run`
- Auth: API key in header `Authorization`

Find the moments in one asset that match a search.

## Path parameters

- `asset_id` string, uuid, required: The ID of the asset to search within

## Request body

- AssetSearchRequest: API request schema for searching within a specific asset.
  - `project_id` string, uuid, required: ID of the project the asset belongs to
  - `spec` UserSearchSpec, required: What to search for and how to filter.
    - `signals` LogicalSignalQuery[], required: Text queries to run, each against one kind of content
      - `signal` 'visual' | 'transcript' | 'document' | 'filename', required: Which content a search signal queries. - `visual`: What's seen. - `transcript`: What's said. - `document`: Text in documents. - `filename`: The file name.
      - `query` string, required: Text query for this logical signal type
    - `filters` Filter[]: Filters to apply to search results
      - `id` string, uuid, required: Attribute ID from `GET /metadata/attributes`.
      - `clause` 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'includes' | 'not_includes' | 'exists' | 'not_exists' | 'is_true' | 'is_false', required: How a filter compares an attribute's value. Each clause works only with the data types listed. - `eq`: Equals one of the values. `string` (ignores case), `integer`, `float`, `datetime`, `single_select`, `directory_id` (assets directly in the directory). - `neq`: Equals none of the values. Same types as `eq`. - `gt`: Greater than the value. `integer`, `float`, `datetime`. - `lt`: Less than the value. `integer`, `float`, `datetime`. - `gte`: Greater than or equal to the value. `integer`, `float`, `datetime`. - `lte`: Less than or equal to the value. `integer`, `float`, `datetime`. - `contains`: Contains one of the values, ignoring case. `string`. - `not_contains`: Contains none of the values, ignoring case. `string`. - `starts_with`: Starts with one of the values, ignoring case. `string`. - `ends_with`: Ends with one of the values, ignoring case. `string`. - `includes`: Has any of the values. `multi_select`, `user_id`, `person_id`, `object_id`, `directory_id` (assets anywhere under the directory). - `not_includes`: Has none of the values. Same types as `includes`. - `exists`: Has a value. Every type except `boolean` and `directory_id`. - `not_exists`: Has no value. Every type except `boolean` and `directory_id`. - `is_true`: Is true. `boolean`. - `is_false`: Is false. `boolean`. `neq`, `not_contains`, `not_includes`, and `is_false` also match assets with no value.
      - `values` unknown[]: Values to compare with, always a list. Leave it empty for `exists`, `not_exists`, `is_true`, and `is_false`. Select attributes take option IDs, ID types take IDs, and `datetime` takes ISO 8601 strings.
        - unknown

## Response `200`

Successful Response

- SearchAssetMetadata: How an asset matched the search.
  - `moments` SearchMoment[]: Where in the asset the search matched
    - `kind` 'visual' | 'transcript' | 'document' | 'filename', required: What a search matched.
    - `start_time` number, nullable: Start of the match in seconds, for video and audio
    - `end_time` number, nullable: End of the match in seconds, for video and audio
    - `page` integer, nullable: Page number, starting at 1, for document matches
    - `query` string, nullable: The query that matched
    - `evidence_text` SearchEvidenceText: Text that matched the search.
      - `excerpt` string, required: A short excerpt of the matching text
  - `confidence` 'unknown' | 'low' | 'medium' | 'high', required: How strong a search match is.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/aspect/apis/aspect-api.md) - [All operations](https://skmtc.dev/aspect/apis/aspect-api/llms.txt) - [OpenAPI document](https://skmtc.dev/aspect/apis/aspect-api/revisions/28ea5f1adb54?raw)