Video Search REST API reference

Endpoint: POST https://api.microsoft.ai/v3/search/videos

Sample Request:

curl -X POST "https://api.microsoft.ai/v3/search/videos" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "cute puppy videos",
    "maxResults": 30,
    "language": "en",
    "region": "US"
  }'

Parameters

Parameter	Required	Type	Default	Description
query	Yes	string	-	A search query string. Maximum length is 1000 characters.
maxResults	No	integer	30	Max number of results to return. Default is 30 and maximum value is 30.
language	No	string	"en"	A 2-letter ISO 639-1 language code for interface language in the search results. See Supported Languages for the full list.
region	No	string	"US"	A 2-letter country/region code for where the results should come from (e.g. "US", "JP", "GB", etc.). See Supported Regions for the full list.
enablePlaylist	No	boolean	false	Whether to include playlist results in response.
freshness	No	string	-	The time range to filter results based on discovery date. Supports "week", "month", "year" for relative time, or ISO 8601 date interval format: "YYYY-MM-DD/YYYY-MM-DD" or "YYYY-MM-DDTHH:mm:ssZ/YYYY-MM-DDTHH:mm:ssZ" for a date/datetime range, use .. to omit start or end date.
embeddable	No	array of string	-	Filter videos by embedding capabilities. Allowed values: "player" (has embeddable player). When not set, no filtering is applied.
resolution	No	string	-	Filter videos by minimum resolution. Values: "360p", "480p", "720p", "1080p". When not set, no filtering is applied.
safeSearch	No	string	"strict"	Level of safe search filtering. Values: "off", "strict". Default is "strict".
duration	No	string	-	Filter videos by duration range. Values: "short" (<5 min), "medium" (5–20 min), "long" (>20 min). When not set, no filtering is applied.

Request Headers

Field	Type	Description
host	string	Host for Microsoft AI APIs: api.microsoft.ai.
x-apikey or Authorization	string	Your API key or Entra ID access token for authentication.
content-type	string	MIME type of the request body. Use application/json.

Response

Videos Response

Field	Type	Description
videoResults	array of videoResult	List of video results.
playlists	array of playlistResult (optional)	List of playlist results.
instrumentationClickBase	string	Base URL for click ping requests. Append an instrumentationSuffix value from a result item to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag. Note: User clicks can also be logged using URL redirection. When redirection is enabled, no action is required to log User clicks, and instrumentationClickBase will not be included in the response. See the Instrumentation guide for setup instructions.
instrumentationCitationBase	string	Base URL for LLM log ping requests. Append a DATA payload to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag.
traceId	string	Trace ID for debugging.

Note

playlists is an optional field even when enablePlaylist is set to true.

videoResult

Field	Type	Description
title	string	The title or name of the video.
url	string	The source URL of the video. For China users with URL redirection enabled, this field instead contains the same redirect URL as clickUrl.
domain	string	The destination host for the result. Returned only for China users with URL redirection enabled.
description	string	Description of the video content. This is either provided by the video uploader or generated by an LLM.
publishedBy	string	Uploader or publisher of the video.
viewCount	long	The number of views the video has.
summary	string	AI-generated video summary.
length	string	The length of the video in HH:MM:SS format.
allowHttpsEmbedding	boolean	Whether HTTPS embedding is allowed.
allowMobileEmbedding	boolean	Whether mobile embedding is allowed.
embeddingUrl	string	URL for embedding the video.
lastUpdatedAt	string	The last updated date as a formatted string.
bestMomentIndex	integer	Index of the best moment or highlight in the video.
moments	array of moment	Array of video segments/moments.
thumbnailUrl	string	Thumbnail URL of the video.
width	integer	The width of the video in pixels.
height	integer	The height of the video in pixels.
isAdult	boolean	Indicates whether the result includes adult content.
clickUrl	string	Redirect URL that proxies the click through Bing. Only present when click redirect is enabled.
instrumentationSuffix	string	Suffix to append to the instrumentation ping URL base for this result item. Used as the K value for both the instrumentation ping URL and the clickUrl redirect. Present when instrumentation ping is enabled.

Note

Several of the above fields are optional – they are served if they are available.

moment

Field	Type	Description
title	string	Title of the moment segment.
description	string	Description of what happens in this moment.
startTime	string	Start time of the moment in format 'd.hh:mm:ss'.
endTime	string	End time of the moment in format 'd.hh:mm:ss'.
momentUrl	string	Direct URL to this specific moment in the video.

Note

moment is an optional response object. It is not available for every video result.

playlistResult

Field	Type	Description
title	string	Title of the playlist.
description	string	Description of the playlist.
videos	array of video	Array of videos in the playlist.

Note

playlistResult is an optional response object.

video

Field	Type	Description
title	string	Title of the video.
description	string	Description of the video.
url	string	URL of the video.

Error Codes

Status Code	Error Category	Description	Common Causes
200	Success	The request succeeded.	-
400	Bad Request	Invalid request parameters.	Missing required fields, invalid parameter values, malformed JSON
401	Unauthorized	Authentication failed or missing.	Invalid API key, missing x-apikey header
403	Forbidden	Valid credentials but insufficient permissions.	API key lacks required permissions
410	Gone	HTTPS required.	Request made over HTTP instead of HTTPS
415	Unsupported Media Type	Content type not supported.	Missing or incorrect content-type header
429	Too Many Requests	Rate limit exceeded.	Too many requests in time window
500	Internal Server Error	Unexpected server error.	Temporary server issue
503	Service Unavailable	Service temporarily unavailable.	Maintenance or temporary outage
504	Gateway Timeout	Request timed out.	Upstream service timeout

For detailed error handling guidance, see Error Handling.

---

See also: Web Search | Browse | News Search | Images Search | MCP