Media and social · YouTube Data API + SearchApi

youtube.search

Searches YouTube videos. details returns statistics, duration and description; transcript fetches the spoken text (paid).

Operation: POST /v1/capabilities/youtube.search/execute
operationId: executeYoutubeSearch
Typical credits: 0
Search deadline: 15 s server-side
Paging: token
Availability: ConfiguredChecked 2026-09-23 21:02 UTC

Cost basis: Search: free quota. Transcript: $0.004 per video. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request

Body of POST /v1/capabilities/youtube.search/execute, JSON, validated against the YoutubeSearchRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of youtube.search
Field	Type	Required	Default	Constraints and description
query	string	yes		min length 1, max length 300
num	integer	no	10	min 1, max 50 Results per page (1-50).
published_after	string (date-time)	no		format date-time RFC 3339, e.g. "2025-01-01T00:00:00Z".
duration	"short" \| "medium" \| "long"	no

Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

Record actions need the video id stored with the record.

Examples

Long talks

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/youtube.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"rust async explained","duration":"long","num":5}'

No recorded response is published for this capability yet. The envelope is the ExecuteResponse component (see sessions and records); the record keys below are what the adapter emits. A first call with the example above returns search_id, the records and the charge.

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the YoutubeSearchRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Record keys of youtube.search
Key	Type	Presence
channel	string	when the source has it
published_at	string	when the source has it
thumbnail	string	when the source has it

Caveats

thumbnail is the medium size when the source offers it, otherwise the default size.
transcript detail: text (at most 60,000 characters), segments (count), language, available_languages, and timestamps: [{ start, duration, text }] in seconds, capped at 2,000 entries with timestamps_truncated: true when capped.

Follow-ups

Paging: Provider cursor; more fetches the next page from the source. Send { "search_id": "…", "action": "more" } while has_more is true; tolerate an empty page and stop after a bounded number of pages.
Update: Re-run with changed parameters (merged into the stored query); page state resets, search_id stays. Params accept any subset of the request fields (YoutubeSearchUpdateParams).
Record actions:
- details: View/like counts, duration, full description.
- transcript: Transcript text with timestamps ($0.004).
Detail behaviour: First details call fetches from the provider (billed as stated); repeats are cached and free. details uses free API quota; transcript costs $0.004 per video.

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

`details` detail keys (owned, documented tier)

Video statistics and description from the YouTube Data API; every key omitted when absent. Built entirely by our code and published as the YoutubeSearchDetailsDetail component; the wire contract of detail stays untyped, extra keys may appear.

Detail keys of youtube.search details
Field	Type	Required	Constraints and description
title	string	no
channel	string	no
published_at	string	no
duration_seconds	integer	no
views	number	no
likes	number	no
comments	number	no
description	string	no	At most 3,000 characters.
tags	string[]	no	max items 10
definition	string	no

`transcript` detail keys (owned, documented tier)

Transcript text with timestamps; $0.004 per video. Built entirely by our code and published as the YoutubeSearchTranscriptDetail component; the wire contract of detail stays untyped, extra keys may appear.

Detail keys of youtube.search transcript
Field	Type	Required	Constraints and description
language	string	yes
available_languages	string[]	yes
segments	integer	yes	min 0 Number of source segments.
text	string	no	At most 60,000 characters.
timestamps	object[]	yes	max items 2000
timestamps[].start	number	yes	Seconds.
timestamps[].duration	number	no	Seconds.
timestamps[].text	string	yes
timestamps_truncated	true	no

Other record detail objects are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/youtube.search/execute", {
  body: {
    "query": "rust async explained",
    "duration": "long",
    "num": 5
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);