Quickstart

Set your Apify token, submit the input and receive an array of Dataset rows.

POSThttps://api.apify.com/v2/acts/meka.im~youtube-channel-scraper/run-sync-get-dataset-items

Apify API token

Set APIFY_TOKEN in your server environment and send Authorization: Bearer. Runs execute under your Apify account.

curl -X POST 'https://api.apify.com/v2/acts/meka.im~youtube-channel-scraper/run-sync-get-dataset-items' \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"channels":["https://www.youtube.com/@NASA"],"tabs":["videos"],"sort":"latest","maxResults":3,"includeChannelInfo":true,"includeDescription":false}'

Examples run on your server. Executing an Actor may incur charges under your Apify account. View Actor details

Input parameters

Send a JSON object as the request body.

Field	Type	Description
`channels`Optional	`array`	Public YouTube channel handles, IDs or URLs. Empty input succeeds with no results or result charges.
`tabs`Optional	`array`	Legacy mode: processed in this order under a shared maxResults cap. Independent limits override tabs when maxResultsShorts or maxResultStreams is supplied. Default: ["videos"].
`sort`Optional	`string`	Uses YouTube native category ordering; unsupported orders are reported as category errors.
`maxResults`Optional	`integer`	Legacy mode: shared maximum per channel (1–1000). Independent mode: videos maximum (0–1000), enabled by maxResultsShorts or maxResultStreams. Duplicates across channels are delivered once. Default: 30. Range: 0–1000.
`includeDescription`Optional	`boolean`	Additional public watch request only for selected items. Failed enrichment retains the basic row and descriptionComplete=false. Default: false.
`maxResultsShorts`Optional	`integer`	Optional: supplying this activates independent category limits. Unspecified Shorts and Streams limits are zero. Set all three limits to zero for channel-only output. Range: 0–1000.
`maxResultStreams`Optional	`integer`	Optional: supplying this activates independent category limits. Unspecified Shorts and Streams limits are zero. Set all three limits to zero for channel-only output. Range: 0–1000.
`detailConcurrency`Optional	`integer`	Maximum simultaneous selected-item detail requests. Results retain channel-list order. Default: 8. Range: 1–32.
`oldestPostDate`Optional	`string`	Optional YYYY-MM-DD (UTC day boundary) or N day / N days (rolling run-start cutoff). Forces latest order. Unknown and boundary-uncertain dates are retained and reported in OUTPUT.dateFilter.
`includeChannelInfo`Optional	`boolean`	Fetch channel About once per channel. Profile fields appear in OUTPUT.channels and CHANNELS.json; unavailable fields remain null. Adds up to one upstream request per channel. Default: false.
`startUrls`Optional	`array`	Alternative to channels. Public YouTube channel URLs only; cannot be combined with channels.
`sortVideosBy`Optional	`string`	Alternative to sort; cannot be combined with sort.
`outputFormat`Optional	`string`	streamers writes COMPATIBILITY.json using competitor field names plus explicit precision and semantics. Dataset remains v1. Default: "v1".

Response fields

The synchronous endpoint returns a JSON array. Each row follows the Actor’s published Dataset contract.

Field	Type	Description
`id`	`string`	Source identity; YouTube IDs identify videos.
`url`	`string`	Canonical YouTube video or Shorts URL.
`title`	`string`	Public video title.
`contentType`	`string`	video, short or stream.
`channelId`	`string \| null`	Available public channel ID.
`channelUrl`	`string \| null`	Available public channel URL.
`channelTitle`	`string \| null`	Available public channel title.
`description`	`string \| null`	Full public description if requested and available; otherwise null or available listing evidence.
`displayedDate`	`string \| null`	Available source calendar date; not an inferred exact timestamp.
`publishedAt`	`string \| null`	Always null; exact timestamps are not inferred from relative labels.
`publishedText`	`string \| null`	Original relative or public display date label.
`dateSource`	`string \| null`	Source evidence for displayed date, or unknown.
`viewsText`	`string \| null`	Original displayed view count, including abbreviations.
`viewsPrecision`	`string \| null`	Count precision evidence; abbreviated_or_unparsed values must not be treated as exact counts.
`durationText`	`string \| null`	Original displayed duration.
`thumbnail`	`string \| null`	Public image URL reference; may expire.
`sourceChannel`	`string`	Submitted channel reference associated with this row.
`views`	`number \| null`	Exact count only when supported by source evidence; abbreviations remain null here.
`durationSeconds`	`number \| null`	Available duration in seconds.
`descriptionComplete`	`boolean`	True only for a complete verified description.
`contractVersion`	`integer`	Native Dataset contract version: 1.
`detailsStatus`	`string \| null`	ok, unavailable or not_requested; failed optional detail preserves the listing row.
`sortRequested`	`string \| null`	Requested ordering.
`sortStatus`	`string \| null`	confirmed, requested_unconfirmed or null. Unsupported sorts are reported as category errors.
`liveStatus`	`string \| null`	live, upcoming or null; concurrent audience differs from accumulated views.

Example response

Historical recording

Selected fields from the Actor README’s October 13, 2026 recording. This is an excerpt, not a full Dataset row or a guarantee of future values.

Selected Dataset fields

[
  {
    "contractVersion": 1,
    "id": "ErAqN6gXqZQ",
    "url": "https://www.youtube.com/watch?v=ErAqN6gXqZQ",
    "title": "NASA's SpaceX Crew-13 Mission (Official NASA Trailer)",
    "contentType": "video",
    "channelTitle": "NASA",
    "description": null,
    "descriptionComplete": false,
    "publishedText": "12d ago",
    "publishedAt": null,
    "views": null,
    "viewsText": "101K",
    "viewsPrecision": "abbreviated_or_unparsed",
    "durationSeconds": 62,
    "durationText": "1:02",
    "detailsStatus": "not_requested",
    "sortRequested": "latest",
    "sortStatus": "confirmed",
    "liveStatus": null
  }
]

Errors & limitations

Run lifecycle

The synchronous endpoint waits at most 300 seconds. For larger batches, start an asynchronous Actor run, wait for completion and retrieve the Dataset and run key-value records. Inspect OUTPUT before interpreting partial delivery as complete.

Public source availability

Removed, restricted, unavailable or changing source content can produce fewer rows or errors. Successful platform status alone does not prove complete collection. No login credentials, private content or media downloads are supported.

For HTTP errors and run lifecycle handling, see the Apify API reference.

Native Dataset and separate records

The synchronous endpoint returns native v1 video Dataset rows only. Channel profiles are written separately to the run key-value store as CHANNELS.json, and OUTPUT contains delivery, category errors, date uncertainty and budget status. Fetch those records via the run key-value store when needed.

outputFormat:streamers adds COMPATIBILITY.json formatVersion 2 with items and diagnostics; it never replaces or changes the native Dataset. The synchronous Dataset response does not include these separate records.

Empty API input returns zero rows. For channel-only collection set maxResults, maxResultsShorts and maxResultStreams all to zero and includeChannelInfo:true. maxResults:0 alone is invalid; channel-only profiles appear in CHANNELS.json.

Limits, counts and dates

In legacy mode maxResults is a shared per-input cap across tabs. Supplying maxResultsShorts or maxResultStreams activates independent category limits: videos uses maxResults, omitted Shorts/streams limits become zero, and tabs is overridden. Categories run videos, then Shorts, then streams.

Distinct trimmed channel references retain separate quotas, while shared video IDs are delivered only once globally. Limits are upper bounds. Unsupported native sorts are reported as errors, and sortStatus records the evidence. oldestPostDate forces latest ordering.

Abbreviated counts and relative ages are preserved rather than converted into exact values. publishedAt stays null. Unknown dates or relative intervals crossing the cutoff are retained and reported; a complete date range is not guaranteed. Optional description failure keeps the valid listing row.

Same-run recovery can retain Dataset IDs and saved state, but the October 14 live test did not verify aborted-run resurrection. A new run has independent output and billing.

Frequently asked questions

Why does a channel-only run return an empty array?

There are no video Dataset rows in channel-only mode. Read CHANNELS.json from the run key-value store.

Why are counts or timestamps null?

Source abbreviations and relative ages are not exact evidence. Inspect viewsText, viewsPrecision, publishedText, displayedDate and dateSource.