# Search (/en/docs/api/compatible/cloudinary/search) [Guide →](/en/docs/developers/services/media/quickstart) Only the following expression subset is supported. Unsupported syntax or fields return HTTP 400 INVALID\_EXPRESSION; compatible errors contain only the message. Tags and context are omitted by default; request them with with\_field. | Syntax | Meaning | | --- | --- | | AND / OR / NOT / - / ( ) | Boolean combinations; adjacent terms imply AND | | field:value / field=value | Field match | | bytes > 1000 / width >= 160 | Numeric comparisons; also height and duration | | created_at >= 2026-01-01 / uploaded_at > 7d | Dates or relative time, d/w/m/y | | tags:docs / context.alt:"sample image" | Tags and custom text | | public_id:docs* | Trailing wildcard only | | "sample image" | Phrase | | sunset | Bare word: full-text match over public_id, display_name, tags, context, and understood captions, image text, and transcripts; case-insensitive | | ~ / ^ / [a TO z] / *prefix / a*b | Unsupported; returns 400 | Field names are case-insensitive (RESOURCE\_TYPE:image equals resource\_type:image). Values of resource\_type, type, and format are case-insensitive; values of tags, context, and other fields are case-sensitive. An empty expression returns every asset; an expression that cannot be parsed returns 400 INVALID\_EXPRESSION. Queryable fields: `asset_id, resource_type, type, format, public_id, asset_folder, display_name, tags, bytes, width, height, duration, created_at, uploaded_at, context.`. Sort fields: `created_at, public_id, display_name, bytes, uploaded_at`. Aggregate fields: `resource_type, format, asset_folder, processing_state`. [Guide →](/en/docs/developers/services/media/quickstart) [Base URL and authentication](/en/docs/api/compatible/cloudinary) ## Visual search [#visual-search] `GET /cloudinary/v1_1/{library_id}/resources/visual_search` | Parameter | Location | Type | Description | | --- | --- | --- | --- | | library_id | path | string | Library ID | | image_asset_id | query | string | Asset ID in this library | | image_url | query | string | Only delivery URLs from this library; external URLs are not fetched | | text | query | string | Natural-language query using semantic search | | max_results | query | integer | Up to 500; Search defaults to 100, Admin to 10 | | filter | query | string | Expression filter | Returns: `VisualResources`. Available when library `search.image` is true; unsupported libraries return LIBRARY\_INVALID\_STATE. JPEG, PNG, WebP and GIF are accepted, with a maximum decoded size of 10 MiB. Each asset returns its highest-scoring match; videos identify the best frame. qwen3-vl-embedding uses 0.35 for image similarity. Measurements on 2026-10-10: variants of the same image scored 0.82–0.96, similar scenes 0.38–0.66, and unrelated images at most 0.34. Provide exactly one of `image_asset_id`, multipart `image_file`, `image_url`, or `text`. Text uses semantic-only search; the response is `{ "resources": [...] }`. image\_url accepts only this library’s delivery URLs. External URLs are never fetched and return 400 with “不支持抓取外部 URL”. ### Response [#response] #### HTTP 200 [#http-200] Successful response. **application/json** | Name | Type | Description | | --- | --- | --- | | resources | array<object> | | | resources[].asset_id | string | | | resources[].public_id | string | | | resources[].display_name | string | | | resources[].asset_folder | string | | | resources[].resource_type | string | | | resources[].type | string | | | resources[].format | string | | | resources[].version | number | | | resources[].version_id | string | | | resources[].bytes | number | | | resources[].etag | string | | | resources[].width | number | | | resources[].height | number | | | resources[].duration | number | | | resources[].pages | number | | | resources[].is_audio | boolean | | | resources[].original_filename | string | | | resources[].tags | array<string> | | | resources[].context | object | | | resources[].created_at | string | | | resources[].url | string | | | resources[].secure_url | string | | | resources[].placeholder | boolean | | | resources[].existing | boolean | | | resources[].processing | object | | ## Visual search [#visual-search-1] `POST /cloudinary/v1_1/{library_id}/resources/visual_search` | Parameter | Location | Type | Description | | --- | --- | --- | --- | | library_id | path | string | Library ID | ### Request body [#request-body] | Field | Type | Required | Description | | --- | --- | --- | --- | | image_asset_id | string | no | Asset ID in this library | | image_url | string | no | Only delivery URLs from this library; external URLs are not fetched | | image_file | string | no | JPEG, PNG, WebP or GIF file, at most 10 MiB | | text | string | no | Natural-language query using semantic search | | max_results | integer | no | Up to 500; Search defaults to 100, Admin to 10 | | filter | string | no | Expression filter | Returns: `VisualResources`. Available when library `search.image` is true; unsupported libraries return LIBRARY\_INVALID\_STATE. JPEG, PNG, WebP and GIF are accepted, with a maximum decoded size of 10 MiB. Each asset returns its highest-scoring match; videos identify the best frame. qwen3-vl-embedding uses 0.35 for image similarity. Measurements on 2026-10-10: variants of the same image scored 0.82–0.96, similar scenes 0.38–0.66, and unrelated images at most 0.34. Provide exactly one of `image_asset_id`, multipart `image_file`, `image_url`, or `text`. Text uses semantic-only search; the response is `{ "resources": [...] }`. image\_url accepts only this library’s delivery URLs. External URLs are never fetched and return 400 with “不支持抓取外部 URL”. ### Response [#response-1] #### HTTP 200 [#http-200-1] Successful response. **application/json** | Name | Type | Description | | --- | --- | --- | | resources | array<object> | | | resources[].asset_id | string | | | resources[].public_id | string | | | resources[].display_name | string | | | resources[].asset_folder | string | | | resources[].resource_type | string | | | resources[].type | string | | | resources[].format | string | | | resources[].version | number | | | resources[].version_id | string | | | resources[].bytes | number | | | resources[].etag | string | | | resources[].width | number | | | resources[].height | number | | | resources[].duration | number | | | resources[].pages | number | | | resources[].is_audio | boolean | | | resources[].original_filename | string | | | resources[].tags | array<string> | | | resources[].context | object | | | resources[].created_at | string | | | resources[].url | string | | | resources[].secure_url | string | | | resources[].placeholder | boolean | | | resources[].existing | boolean | | | resources[].processing | object | | ## Search [#search] `GET /cloudinary/v1_1/{library_id}/resources/search` | Parameter | Location | Type | Description | | --- | --- | --- | --- | | library_id | path | string | Library ID | | expression | query | string | Structured query expression; an empty expression returns every asset | | sort_by | query | string | Sort fields and directions | | max_results | query | integer | Up to 500; Search defaults to 100, Admin to 10 | | next_cursor | query | string | Next-page cursor; null or absent at the end | | with_field | query | string[] | Include tags or context | | aggregate | query | string[] | Aggregation fields | Returns: `CompatExpressionSearchResult`. ### Response [#response-2] #### HTTP 200 [#http-200-2] Successful response. **application/json** | Name | Type | Description | | --- | --- | --- | | total_count | number | | | time | number | | | next_cursor | string | | | resources | array<object> | | | resources[].asset_id | string | | | resources[].public_id | string | | | resources[].display_name | string | | | resources[].asset_folder | string | | | resources[].resource_type | string | | | resources[].type | string | | | resources[].format | string | | | resources[].version | number | | | resources[].version_id | string | | | resources[].bytes | number | | | resources[].etag | string | | | resources[].width | number | | | resources[].height | number | | | resources[].duration | number | | | resources[].pages | number | | | resources[].is_audio | boolean | | | resources[].original_filename | string | | | resources[].tags | array<string> | | | resources[].context | object | | | resources[].created_at | string | | | resources[].url | string | | | resources[].secure_url | string | | | resources[].placeholder | boolean | | | resources[].existing | boolean | | | resources[].processing | object | | | aggregations | object | | ```bash curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/search?expression=tags%3Adocs" \ -H "Authorization: Bearer $PRAXIS_API_KEY" ``` HTTP 200 ```json { "total_count": 1, "time": 0, "resources": [ { "asset_id": "9339cdae93804c0c8c65d5189ef1f646", "public_id": "docs/pixel", "display_name": "Sample image", "asset_folder": "examples", "resource_type": "image", "type": "upload", "format": "png", "version": 1791538418, "version_id": "35848c1529994e338e7aa634a1c13d9c", "bytes": 70, "etag": "b357a19c87624c7c4d131aeeb4ae677f", "width": 1, "height": 1, "original_filename": "file", "created_at": "2026-10-09T09:33:38.899Z", "url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png", "secure_url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png", "placeholder": false } ] } ``` ## Search [#search-1] `POST /cloudinary/v1_1/{library_id}/resources/search` | Parameter | Location | Type | Description | | --- | --- | --- | --- | | library_id | path | string | Library ID | ### Request body [#request-body-1] | Field | Type | Required | Description | | --- | --- | --- | --- | | expression | string | no | Structured query expression; an empty expression returns every asset | | sort_by | object[] | no | Sort fields and directions | | max_results | integer | no | Up to 500; Search defaults to 100, Admin to 10 | | next_cursor | string | no | Next-page cursor; null or absent at the end | | with_field | "tags" / "context"[] | no | Include tags or context | | aggregate | AggregateField[] | no | Aggregation fields | Returns: `CompatExpressionSearchResult`. ### Response [#response-3] #### HTTP 200 [#http-200-3] Successful response. **application/json** | Name | Type | Description | | --- | --- | --- | | total_count | number | | | time | number | | | next_cursor | string | | | resources | array<object> | | | resources[].asset_id | string | | | resources[].public_id | string | | | resources[].display_name | string | | | resources[].asset_folder | string | | | resources[].resource_type | string | | | resources[].type | string | | | resources[].format | string | | | resources[].version | number | | | resources[].version_id | string | | | resources[].bytes | number | | | resources[].etag | string | | | resources[].width | number | | | resources[].height | number | | | resources[].duration | number | | | resources[].pages | number | | | resources[].is_audio | boolean | | | resources[].original_filename | string | | | resources[].tags | array<string> | | | resources[].context | object | | | resources[].created_at | string | | | resources[].url | string | | | resources[].secure_url | string | | | resources[].placeholder | boolean | | | resources[].existing | boolean | | | resources[].processing | object | | | aggregations | object | | ```bash curl -X POST "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/search" \ -H "Authorization: Bearer $PRAXIS_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"expression":"tags:docs"}' ``` HTTP 200 ```json { "total_count": 2, "time": 0, "resources": [ { "asset_id": "9dfa312ef9bc4b00816339b598b1152c", "public_id": "walk-lib-r1-MDP-1791733789929-tagged", "display_name": "walk-lib-r1-MDP-1791733789929-tagged", "asset_folder": "", "resource_type": "image", "type": "upload", "format": "png", "version": 1791733815, "version_id": "26cb8171caa5431b8373ad417fd71e32", "bytes": 70, "etag": "b357a19c87624c7c4d131aeeb4ae677f", "width": 1, "height": 1, "original_filename": "file", "processing": { "state": "processing", "kinds": { "embedding": "running", "visual": "failed", "tagging": "failed" }, "updated_at": "2026-10-11T15:50:21.512Z" }, "created_at": "2026-10-11T15:50:15.996Z", "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png", "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png", "placeholder": false }, { "asset_id": "85b7ef616a8b4719a41777a036ebc1d2", "public_id": "walk-lib-r1-MDP-1791733789929-plain", "display_name": "walk-lib-r1-MDP-1791733789929-plain", "asset_folder": "", "resource_type": "image", "type": "upload", "format": "png", "version": 1791733810, "version_id": "fdf3c8cd40c2424d86e8397425a69857", "bytes": 70, "etag": "b357a19c87624c7c4d131aeeb4ae677f", "width": 1, "height": 1, "original_filename": "file", "created_at": "2026-10-11T15:50:10.842Z", "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png", "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png", "placeholder": false } ] } ``` ## VisualResources [#visualresources] | Field | Type | Required | Description | | --- | --- | --- | --- | | resources | CloudinaryResource[] | yes | Assets in this page | ## CompatExpressionSearchResult [#compatexpressionsearchresult] | Field | Type | Required | Description | | --- | --- | --- | --- | | total_count | number | yes | Matching count | | time | number | yes | Search time in whole milliseconds, measured by the service | | next_cursor | string | no | Next-page cursor; null or absent at the end | | resources | SearchResource[] | yes | Assets in this page | | aggregations | object | no | Counts by requested fields | ## SearchResource [#searchresource] | Field | Type | Required | Description | | --- | --- | --- | --- | | asset_id | AssetId | yes | Asset ID | | public_id | string | yes | Asset name in delivery URLs; may contain path segments | | display_name | string | yes | Display name | | asset_folder | string | yes | Organizational folder; does not change public_id. Listing by it matches that level only, not subfolders; an empty string is the root | | resource_type | ResourceType | yes | image, video (including audio), or raw; auto applies to uploads only, and listing with auto or any other value returns 400 | | type | DeliveryType | yes | Resource or event type | | format | string | yes | File format | | version | number | yes | Delivery version | | version_id | string | yes | Version identifier | | bytes | number | yes | File size in bytes | | etag | string | yes | File checksum | | width | number | no | Width in pixels | | height | number | no | Height in pixels | | duration | number | no | Duration in seconds | | pages | number | no | Document pages | | is_audio | boolean | no | Whether this is audio | | original_filename | string | no | Original file name | | tags | string[] | no | Asset tags. Uploads accept a comma-separated string (items trimmed, empty items dropped), an array, or repeated tags fields; PATCH accepts an array only and replaces the whole list | | context | object | no | Custom text key/value pairs; PATCH replaces the whole map, {} clears it | | created_at | IsoTimestamp | yes | Creation time | | url | string | yes | Original-file URL | | secure_url | string | yes | HTTPS delivery URL | | placeholder | false | yes | Always false | | existing | boolean | no | Whether an existing asset was returned without overwrite | | processing | Processing | no | Overall and per-kind processing states |