---
title: "Search a project"
method: POST
path: "/search/run"
tags: ["Search"]
---

# Search a project

`POST /search/run`

## Request

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

Search a project's assets by what's seen, said, or written in them, and filter by metadata.

## Request body

- SearchRequest: API request schema for end-user project search.
  - `project_id` string, uuid, required: ID of the project to search within
  - `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
  - `limit` integer: Maximum number of assets to return.
  - `offset` integer: Number of matching assets to skip. Only the first 1000 matching assets are returned; a page past them is empty.

## Response `200`

Successful Response

- SearchResponse: Top-level response for project search.
  - `assets` SearchAssetResponse[], required: Matching assets, best match first; a search with only filters sorts them by name.
    - `id` string, uuid, required
    - `type` 'video' | 'image' | 'audio' | 'document' | 'vector' | 'other', required
    - `name` string, required
    - `size_bytes` integer, required
    - `media` AssetMedia: Intrinsic media properties extracted from the asset's content.
      - `width` integer, nullable: Pixel width for visual assets. Null when unknown.
      - `height` integer, nullable: Pixel height for visual assets. Null when unknown.
      - `duration` number, nullable: Duration in seconds for time-based assets. Null for assets without a duration.
      - `frame_rate` number, nullable: Frames per second for video assets. Null for non-video assets.
      - `timecode` string, nullable: SMPTE start timecode, such as `01:00:00:00` (`01:00:00;00` for drop-frame). Null when the file has none.
      - `page_count` integer, nullable: Number of pages for document assets. Null for non-document assets.
    - `mime_type` string, required
    - `is_uploaded` boolean, required
    - `is_generated` boolean: Whether this asset was produced by the AI generation pipeline
    - `workspace_id` string, uuid, required: ID of the workspace this asset belongs to
    - `project_id` string, uuid, required: ID of the project this asset belongs to
    - `parent_id` string, uuid, required: ID of the parent resource (directory or project)
    - `comment_count` integer, required: Total number of visible comments on this asset, including replies
    - `created_by_user_id` string, uuid, required: ID of the user that created the asset
    - `version_stack_id` string, uuid, nullable: Version stack ID. Null if the asset isn't in a stack.
    - `version_number` integer, nullable: Position in the version stack, starting at 1. Null if the asset isn't in a stack.
    - `is_top_version` boolean, nullable: True for the top version of a stack. Null if the asset isn't in a stack.
    - `manifest_id` string, uuid, nullable: ID of the asset's current file content. It changes whenever the content changes. Null when the asset has no content yet.
    - `created` string, date-time, required
    - `updated` string, date-time, required
    - `content_modified_at` string, date-time, required: When the asset's file content last changed. Renames and metadata edits don't change it.
    - `search` SearchAssetMetadata, required: 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.
  - `has_more` boolean, required: Whether more matching assets follow this page; a page can be short even when they do. To get them, send the same request with `offset` increased by `limit`.

## 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)