List knowledge store items

A number that identifies the page to retrieve.

Default: 1.

The number of items to return on each page.

Default: 10. Max: 50.

The field to sort on. The following options are available:

• created_at: Sorts by the time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the item was created.
• updated_at: Sorts by the time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the item was last updated.
• metadata.<key>: Sorts by the value of a custom metadata key. The key is everything after metadata., including any dots. It has 1 to 128 characters. For example, metadata.view_count sorts by the view_count key.

For metadata.<key>, the platform reads the value of the key in the item_metadata field of the item. If the item has no value for the key in that field, the platform uses the value in the metadata field. A value of null or an empty array counts as no value.

In ascending order, the platform groups the values by type in this order: strings, numbers, booleans, arrays of strings. Within each type, the platform sorts by value. The platform treats strings that differ only in case as different values. It does not convert Unicode characters to a standard form before it compares them. It sorts arrays by length first, then element by element. Descending order reverses the order of the types and of the values. Items that have no value for the key come last in both directions. The platform sorts items with equal values by their unique identifiers, in the same direction.

If sort_by is not created_at, updated_at, or a value that starts with metadata., the platform returns a 400 error. If the key is empty, longer than 128 characters, or contains a NUL character, the platform returns a 422 error.

Default: created_at.

The sorting direction. The following options are available:

• asc
• desc

Default: desc.

Filter by one or more item processing statuses. For the meaning of each value, see the Item statuses section on The knowledge store item object page.

To filter by multiple statuses, repeat the status parameter for each value:

status=queued&status=pending

Filter by the unique identifiers of one or more assets. The filter matches items in every status. To also filter by status, use the status parameter.

To filter by multiple assets, repeat the asset_id parameter for each value:

asset_id=6298d673f1090f1100476d4c&asset_id=6298d673f1090f1100476d4d

You can specify up to 50 values. A value that you send twice counts as two values.

An identifier that is valid but belongs to no asset matches no items. The platform returns a 200 response with an empty data array. It does not return an error. If you specify more than 50 values, the platform returns a 400 error with the parameter_invalid code. It returns the same error for an empty value or a value that is not a valid asset identifier.

Filter by custom metadata. Provide a JSON object that maps each key to a value or to a list of values. A list matches any of its values. An item must match all of the keys that you specify.

A key matches the custom metadata of the source asset (the metadata field of the knowledge store item) and the custom metadata of the knowledge store item (the item_metadata field). An item matches a key when the value matches in either field.

A value is a string, a number, or a boolean. The value must have the same type as the value that the item has for the key. For example, the number 2026 does not match the string "2026". If the item has a list for the key, the item matches when the list contains the value.

The object must have at least one key. A list must have at least one value. If the parameter is not a valid JSON object, or a value is not a string, a number, or a boolean, the platform returns a 422 error.

URL-encode the object:

metadata=%7B%22hashtags%22%3A%5B%22summer%22%2C%22travel%22%5D%2C%22verified%22%3Atrue%7D

Filter by enrichment values. The platform extracts these values as the enrichment configuration of the knowledge store defines (the ingestion_config.enrichment_config field).

Provide a JSON object that maps each top-level property that the enrichment configuration defines to a value or to a list of values. Each value follows the rules for the metadata parameter. If you specify a key that the enrichment configuration does not define, the platform returns a 422 error.

The granularity keyword of a property sets how often the platform extracts its value. The keyword also sets which items the key matches:

• video: One value for each video. The key matches video items only.
• image: One value for each image. The key matches image items only.
• shot: One value for each shot of a video. A shot is a continuous part of a video between two scene changes. The key matches video items only. If you specify more than one shot key, one shot must have all of the values.

An item must match all of the keys that you specify. An object with a video key and an image key matches no items, because an item is a video or an image.

URL-encode the object:

enrichment=%7B%22detected_topic%22%3A%22cooking%22%7D

Return only items created at or after this time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”).

The creation time is the time when you create the item with the POST method of the /knowledge-stores/{knowledge_store_id}/items endpoint. It is not the time when the item reaches the ready status. To list only items that are ready, also set the status parameter to ready.

Return only items created at or before this time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”). When you use both created_at_gte and created_at_lte, the created_at_gte time must be equal to or earlier than the created_at_lte time. Otherwise, the platform returns a 422 error.

The creation time is the time when you create the item with the POST method of the /knowledge-stores/{knowledge_store_id}/items endpoint. It is not the time when the item reaches the ready status.