# Lemmy Instance Extractor (`datamule/lemmy-instance-extractor`) Actor Point at ANY Lemmy instance (lemmy.world, sh.itjust.works, lemm.ee…) and pull instance stats, posts, comments or communities into clean flat rows. One actor reads every federated /api/v3 server. Sort + community filters, auto-paged, lossless \_raw. Pay per item. - **URL**: https://apify.com/datamule/lemmy-instance-extractor.md - **Developed by:** [Datamule](https://apify.com/datamule) (community) - **Categories:** Social media, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.35 / 1,000 items This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Lemmy Instance Extractor **Point at ANY Lemmy instance and pull its stats, posts, comments, or communities into clean, flat, tabular rows — one actor for the entire federated network.** [Lemmy](https://join-lemmy.org/) is the open-source, federated link-aggregator (a self-hosted Reddit alternative). Every Lemmy server — `lemmy.world`, `sh.itjust.works`, `lemm.ee`, `programming.dev`, and thousands of others — exposes the **identical, unauthenticated `/api/v3` REST API**. This actor speaks that one grammar, so a single run can read across as many instances as you give it and return comparable rows for every one. No login, no API key, no browser automation — just clean JSON. ### What it does Give it a list of instances and a **mode**, and it returns one flat row per item: | Mode | Endpoint | One row per… | Use it for | |------|----------|--------------|------------| | `site` | `/api/v3/site` | **instance** | A federated-instance **census**: name, version, registration policy, total users/posts/comments/communities, and daily/weekly/monthly/half-year active users. | | `posts` | `/api/v3/post/list` | **post** | Front-page or per-community post feeds — title, URL, body, author, community, score, up/downvotes, comment count. | | `comments` | `/api/v3/comment/list` | **comment** | Comment feeds — content, author, post, community, score, reply count. | | `communities` | `/api/v3/community/list` | **community** | A community directory — name, title, description, subscribers, post/comment counts, active users. | Every row also carries the lossless original object in **`_raw`**, plus `_instance` / `_mode` / `_sort` provenance so multi-instance, multi-mode datasets stay unambiguous. ### Why this instead of a single-instance scraper Most Lemmy scrapers target one instance or one community. This one is **generic**: the same run censuses `lemmy.world` and `sh.itjust.works` and `lemm.ee` side by side, because they all speak the same API. Point it at a fresh instance you've never seen and it just works — the federated-network moat a single-target scraper can't match. ### Input | Field | Type | Description | |-------|------|-------------| | `instances` | array **(required)** | Instances as bare hostnames or base URLs, e.g. `["lemmy.world", "https://sh.itjust.works"]`. | | `mode` | string | `site` (default), `posts`, `comments`, or `communities`. | | `sort` | string | Feed sort order (ignored for `site`). `Active`, `Hot`, `New`, `Old`, `MostComments`, `TopDay`…`TopAll`, `Controversial`, `Scaled`. | | `limit` | integer | Max items **per instance** in feed modes. Lemmy caps a request at 50, so larger values are auto-paged. Default 50. | | `communityName` | string | Optional. Restrict `posts`/`comments` to a community — `technology` or `technology@lemmy.world`. | | `communityId` | integer | Optional. Restrict `posts`/`comments` to a community by numeric ID (takes precedence over name). | | `postId` | integer | Optional. In `comments` mode, restrict to one post's thread. | | `listingType` | string | `All` (federated, default) or `Local` (this instance only) for `posts`/`communities`. | | `userAgent` / `extraHeaders` | string / object | Optional. Not required for public instances. | #### Example — a two-instance census ```json { "instances": ["lemmy.world", "sh.itjust.works"], "mode": "site" } ```` #### Example — top posts of the week from one community ```json { "instances": ["lemmy.world"], "mode": "posts", "sort": "TopWeek", "communityName": "technology", "limit": 100 } ``` ### Notes on Lemmy's API (handled for you) - **`limit` maxes out at 50 per request** — this actor pages the 1-indexed `page` param automatically to reach your total `limit`. - **The comment feed supports fewer sorts** than posts (`Hot`/`Top`/`New`/`Old`/`Controversial`). If you pick a sort a mode doesn't support, it's mapped to the closest valid one — your run never fails on an unsupported sort. - **Resilient by instance**: an instance that's down, rate-limited, or isn't a Lemmy server is skipped with a warning and the run continues. If *every* instance fails, the run errors out rather than returning a misleading empty result. ### Pricing **Pay-per-result**: you're charged one **item** event per row emitted (one per instance in `site` mode; one per post/comment/community in the feed modes). No monthly rental. ### Output row (fields) Provenance `_source` / `_instance` / `_mode` / `_sort`; identity `id` / `name` / `title` / `body` / `url` / `ap_id` / `published` / `updated`; flags `local` / `nsfw` / `removed` / `deleted` / `locked`; actors `creator_id` / `creator_name` / `creator_actor_id`; relations `community_*` / `post_id` / `post_name`; item counts `score` / `upvotes` / `downvotes` / `num_comments` / `child_count`; container counts `subscribers` / `subscribers_local` / `num_posts` / `num_communities` / `users` / `active_day|week|month|half_year`; instance `instance_version` / `registration_mode` / `admins_count`; and the lossless `_raw`. Every field is nullable — a mode fills its subset and leaves the rest empty. # Actor input Schema ## `instances` (type: `array`): One or more Lemmy instances as bare hostnames or base URLs. Every federated Lemmy server speaks the identical unauthenticated /api/v3 REST API, so point this at as many as you like. Examples: lemmy.world, https://sh.itjust.works, lemm.ee, programming.dev. An instance that is down or is not a Lemmy server is skipped with a warning and the run continues. ## `mode` (type: `string`): Which Lemmy collection to read from each instance. site = the instance's own metadata + live stats (one row per instance — a federated-instance census). posts / comments / communities = a paginated feed (one row per item), honouring the sort and, for posts/comments, an optional community filter. ## `sort` (type: `string`): Sort order for feed modes (ignored for site mode). Note: Lemmy's comment feed only supports Hot / Top / New / Old / Controversial — any other sort you pick is automatically mapped to the closest comment-valid sort, so your run never fails on an unsupported sort. Posts and communities support the full set below. ## `limit` (type: `integer`): Maximum number of items to fetch PER INSTANCE in feed modes (posts / comments / communities). Lemmy caps a single API request at 50 items, so larger values are fetched by paging automatically. Ignored in site mode (always one row per instance). Each emitted row is one billable event. Default 50. ## `communityName` (type: `string`): Optional. Restrict posts / comments to a single community. Use a local name (technology) or a fully-qualified federated name (technology@lemmy.world). Ignored for site / communities modes and when Community ID is set. ## `communityId` (type: `integer`): Optional. Restrict posts / comments to a community by its numeric local ID on the target instance. Takes precedence over Community name. Ignored for site / communities modes. ## `postId` (type: `integer`): Optional. In comments mode, restrict to the comment thread of a single post by its numeric ID on the target instance. Ignored in other modes. ## `listingType` (type: `string`): Optional listing scope for posts / communities modes. All = the whole federated view (default). Local = only content originating on that instance. (Subscribed / ModeratorView require a logged-in account and are not useful unauthenticated.) ## `userAgent` (type: `string`): Optional custom User-Agent header. A descriptive default is sent if left empty. Some instances rate-limit or block generic agents. ## `extraHeaders` (type: `object`): Optional extra HTTP headers to send with every request, as a JSON object. Not required for public instances (the Lemmy read API needs no auth). Never logged. ## Actor input object example ```json { "instances": [ "lemmy.world", "sh.itjust.works" ], "mode": "site", "sort": "Active", "limit": 50, "listingType": "All" } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "instances": [ "lemmy.world", "sh.itjust.works" ], "limit": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("datamule/lemmy-instance-extractor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "instances": [ "lemmy.world", "sh.itjust.works", ], "limit": 50, } # Run the Actor and wait for it to finish run = client.actor("datamule/lemmy-instance-extractor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "instances": [ "lemmy.world", "sh.itjust.works" ], "limit": 50 }' | apify call datamule/lemmy-instance-extractor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=datamule/lemmy-instance-extractor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Lemmy Instance Extractor", "description": "Point at ANY Lemmy instance (lemmy.world, sh.itjust.works, lemm.ee…) and pull instance stats, posts, comments or communities into clean flat rows. One actor reads every federated /api/v3 server. Sort + community filters, auto-paged, lossless _raw. Pay per item.", "version": "0.1", "x-build-id": "ioLxY4Y3CBbTPyd76" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datamule~lemmy-instance-extractor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datamule-lemmy-instance-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/datamule~lemmy-instance-extractor/runs": { "post": { "operationId": "runs-sync-datamule-lemmy-instance-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/datamule~lemmy-instance-extractor/run-sync": { "post": { "operationId": "run-sync-datamule-lemmy-instance-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "instances" ], "properties": { "instances": { "title": "Lemmy instance(s)", "type": "array", "description": "One or more Lemmy instances as bare hostnames or base URLs. Every federated Lemmy server speaks the identical unauthenticated /api/v3 REST API, so point this at as many as you like. Examples: lemmy.world, https://sh.itjust.works, lemm.ee, programming.dev. An instance that is down or is not a Lemmy server is skipped with a warning and the run continues.", "items": { "type": "string" } }, "mode": { "title": "Mode (what to extract)", "enum": [ "site", "posts", "comments", "communities" ], "type": "string", "description": "Which Lemmy collection to read from each instance. site = the instance's own metadata + live stats (one row per instance — a federated-instance census). posts / comments / communities = a paginated feed (one row per item), honouring the sort and, for posts/comments, an optional community filter.", "default": "site" }, "sort": { "title": "Sort", "enum": [ "Active", "Hot", "New", "Old", "MostComments", "TopDay", "TopWeek", "TopMonth", "TopYear", "TopAll", "Controversial", "Scaled" ], "type": "string", "description": "Sort order for feed modes (ignored for site mode). Note: Lemmy's comment feed only supports Hot / Top / New / Old / Controversial — any other sort you pick is automatically mapped to the closest comment-valid sort, so your run never fails on an unsupported sort. Posts and communities support the full set below.", "default": "Active" }, "limit": { "title": "Limit (items per instance)", "minimum": 1, "type": "integer", "description": "Maximum number of items to fetch PER INSTANCE in feed modes (posts / comments / communities). Lemmy caps a single API request at 50 items, so larger values are fetched by paging automatically. Ignored in site mode (always one row per instance). Each emitted row is one billable event. Default 50.", "default": 50 }, "communityName": { "title": "Community filter (name)", "type": "string", "description": "Optional. Restrict posts / comments to a single community. Use a local name (technology) or a fully-qualified federated name (technology@lemmy.world). Ignored for site / communities modes and when Community ID is set." }, "communityId": { "title": "Community filter (numeric ID)", "type": "integer", "description": "Optional. Restrict posts / comments to a community by its numeric local ID on the target instance. Takes precedence over Community name. Ignored for site / communities modes." }, "postId": { "title": "Post filter (numeric ID)", "type": "integer", "description": "Optional. In comments mode, restrict to the comment thread of a single post by its numeric ID on the target instance. Ignored in other modes." }, "listingType": { "title": "Listing type", "enum": [ "All", "Local" ], "type": "string", "description": "Optional listing scope for posts / communities modes. All = the whole federated view (default). Local = only content originating on that instance. (Subscribed / ModeratorView require a logged-in account and are not useful unauthenticated.)", "default": "All" }, "userAgent": { "title": "User-Agent (optional)", "type": "string", "description": "Optional custom User-Agent header. A descriptive default is sent if left empty. Some instances rate-limit or block generic agents." }, "extraHeaders": { "title": "Extra request headers (optional)", "type": "object", "description": "Optional extra HTTP headers to send with every request, as a JSON object. Not required for public instances (the Lemmy read API needs no auth). Never logged." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```