PeerTube Instance Harvester

Point at any PeerTube instance and export its videos, channels and instance metadata to a structured dataset — from the public /api/v1 REST API.

PeerTube is the ActivityPub-federated, self-hosted alternative to YouTube. Every instance — framatube.org, makertube.net, tube.tchncs.de and thousands more — exposes the identical public /api/v1 REST API with no auth for public content. This one actor works against all of them: no per-instance scraper, no host enumeration. Give it an instance URL and it turns that instance's video timeline, search results, channel directory, or server metadata into clean rows.

Why this actor

Most "PeerTube" tools on the market clone a single instance or scrape the web UI. This is a generic runner over the protocol — the same field is read by key presence on every instance, so an instance that omits an optional field yields null for that column instead of breaking. One actor, thousands of federated video sources.

It also captures federation correctly: a video listed on framatube.org may actually live on tube.tchncs.de. The real origin host is captured on every row, alongside the instance you queried (_source).

Modes

The run mode is chosen from your input:

Mode	How to trigger	What you get
Videos (default)	mode: videos (or just an instance URL)	One row per video from /api/v1/videos. Add a search term to use /api/v1/search/videos. Sort with sort (default newest first).
Channels	mode: channels	One row per channel from /api/v1/video-channels (name, host, followers, owner account).
Discovery	mode: discovery or listOnly: true	One row describing the instance: name, server version, signup policy, short description, total video count. A cheap way to inspect an instance.

Input

Field	Type	Description
instanceUrl	string (required)	Root of a PeerTube instance, e.g. https://framatube.org. The /api/v1 path is appended for you.
mode	string	videos (default), channels, or discovery.
search	string	Videos mode: free-text search across the instance's federated index.
sort	string	Videos mode: sort order (default -publishedAt). Also accepts -views, -likes, -trending, name, …
includeNsfw	boolean	Videos mode: include NSFW videos (default false).
listOnly	boolean	Shortcut for discovery mode.
maxRecords	integer	Global cap on rows emitted (deterministic sample).
bearer	string (secret)	Optional token for a private / rate-limited instance. Never required for public content, never logged.
extraHeaders	object	Optional extra HTTP headers for gated instances.

Example — newest videos from Framatube

{ "instanceUrl": "https://framatube.org", "mode": "videos", "maxRecords": 50 }

Example — search a large instance

{ "instanceUrl": "https://makertube.net", "search": "blender", "maxRecords": 100 }

Example — inspect an instance cheaply

{ "instanceUrl": "https://tube.tchncs.de", "listOnly": true }

Output

One flat, fully-nullable row per record. Video rows include: id, uuid, shortUUID, name, description, url (canonical watch URL), duration, views, likes, dislikes, nsfw, isLive, publishedAt, originallyPublishedAt, promoted category / licence / language / privacy labels, channelName / channelDisplayName / channelUrl, accountName / accountUrl, host (the real federating instance), thumbnailPath / previewPath / embedPath, plus a lossless _raw object holding the complete original record.

{
  "_type": "video",
  "_source": "https://framatube.org",
  "_mode": "videos",
  "name": "Wie fährst du dein Projekt zuverlässig an die Wand?",
  "url": "https://tube.tchncs.de/videos/watch/007c7bd1-5860-40f4-9850-e8c57a0867c1",
  "duration": 3799,
  "views": 4,
  "likes": 1,
  "category": "Science & Technology",
  "language": "German",
  "channelDisplayName": "Software Architektur im Stream",
  "host": "tube.tchncs.de",
  "publishedAt": "2026-07-06T09:00:32.097Z"
}

Pricing

Pay-per-event: one Video event per emitted row (video, channel, or instance record). You only pay for records you receive.

Notes

• An empty instance or a no-match search returns 0 records and a clean exit.
• A URL that is not a PeerTube instance (an HTML page, a 404, JSON without the expected shape) fails fast with a clear message — nothing is fabricated.
• Find instances via the PeerTube instances directory.