# Flathub Apps Scraper (`kawsar/flathub-apps-scraper`) Actor

Extract Linux Flatpak application details, search by keywords, or fetch install statistics. Results can be downloaded as JSON, CSV, or Excel dataset formats.

- **URL**: https://apify.com/kawsar/flathub-apps-scraper.md
- **Developed by:** [Kawsar](https://apify.com/kawsar) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.99 / 1,000 results

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Flathub Apps Scraper: Linux Flatpak Apps Data Collector

This tool lets you gather detailed metadata and download statistics for Linux Flatpak applications available on Flathub. Whether you want to pull details for a specific tool, search by keywords like "editor", or check monthly install numbers, you can easily export the data in CSV, JSON, or Excel format.

This actor operates independently and is built to help developers, analysts, and open-source enthusiasts collect application insights smoothly.

### Use Cases

- **Targeted App Lookup**: Look up specific software (e.g., `org.mozilla.firefox`) to keep track of its name, summary, developer, license, and icon URL.
- **Keyword Search**: Discover software by searching for keywords such as "editor" or "media" and paginate through the results.
- **Install Metrics**: Track usage trends by collecting total downloads and recent monthly install counts for specific application IDs.
- **Fleet & Catalog Lists**: Build comprehensive software catalogs, control overall item caps, toggle statistics on or off, and export structured tables.
- **Automated Monitoring**: Run scheduled jobs to monitor updates or download trends across software titles over time.

### Data Fields Extracted

Depending on the mode you choose, the tool extracts the following fields:

| Field | Type | Description |
| --- | --- | --- |
| `app_id` | string | Standard Flatpak application identifier. |
| `name` | string | Display name of the application. |
| `summary` | string | Brief description or tag line. |
| `developer_name` | string | Person or organization behind the app. |
| `project_license` | string | Open-source or proprietary software license. |
| `main_categories` | string | Primary application category (e.g., office, utility). |
| `verification_verified` | boolean | Indicates whether the publisher is officially verified. |
| `installs_last_month` | integer | Total downloads recorded over the last month. |
| `updated_at` | integer | Unix timestamp of the latest catalog update. |
| `icon` | string | Direct link to the app's icon image. |
| `installs_total` | integer | Total cumulative downloads. |
| `url` | string | Direct web link to the app listing page. |
| `scraped_at` | string | UTC timestamp marking when the data was collected. |

### Input Options

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | string | `app` | Choose between looking up specific apps, searching by text, or pulling install stats. |
| `query` | string | `editor` | Search keywords (used when mode is set to search). |
| `appIds` | array | `["org.mozilla.firefox"]` | List of application IDs to fetch (used in app or stats mode). |
| `includeStats` | boolean | `true` | Fetch install metrics along with application details. |
| `requestDelaySecs` | number | `1` | Delay between consecutive requests to prevent network overload. |
| `userAgent` | string | `kawsarActorResearch/1.0` | Custom headers sent with requests. |
| `timeoutSecs` | integer | `300` | Overall run duration limit in seconds. |
| `requestTimeoutSecs` | integer | `30` | Timeout per individual network request. |
| `proxyConfiguration` | object | `{}` | Optional proxy settings if required. |

#### Example Input Configuration

```json
{
  "mode": "search",
  "query": "editor",
  "appIds": ["org.mozilla.firefox"],
  "includeStats": true,
  "requestDelaySecs": 1,
  "userAgent": "AppResearch/1.0",
  "timeoutSecs": 300,
  "requestTimeoutSecs": 30
}

```

#### Example Output Data

```json
{
  "app_id": "org.onlyoffice.desktopeditors",
  "name": "ONLYOFFICE Desktop Editors",
  "summary": "Office productivity suite",
  "developer_name": "ONLYOFFICE",
  "project_license": "AGPL-3.0-only",
  "main_categories": "office",
  "verification_verified": true,
  "installs_last_month": 84248,
  "updated_at": 1779470741,
  "icon": "https://dl.flathub.org/media/org/onlyoffice/desktopeditors/5602da018a6ffaae80da2f668f0113e0/icons/128x128/org.onlyoffice.desktopeditors.png",
  "url": "https://flathub.org/apps/org.onlyoffice.desktopeditors",
  "scraped_at": "2026-10-12T00:00:00+00:00"
}

```

### How It Works

1. **Initialization**: Parses your configuration, sets request parameters, and initializes the queue.
2. **Data Collection**: Retrieves application listings or iterates through multi-page search results based on your target mode.
3. **Normalization**: Deduplicates repeated application entries by ID, formats all numeric and text fields consistently, and attaches collection timestamps.
4. **Resilience & Storage**: Retries transient request failures smoothly and writes structured results directly to your storage dataset.

### Frequently Asked Questions

**Can I export the extracted data to CSV or Excel?**

Yes. You can download the dataset directly in JSON, CSV, Excel, or XML format.

**How does deduplication work?**

Entries are automatically deduplicated by their unique application ID during execution so you receive clean datasets without repeated rows.

**What happens when an invalid application ID is provided?**

If an application ID cannot be found, the runner captures the issue cleanly in an error log row so the rest of your run continues without interruption.

### Trademark Notice

Flathub and related application names, logos, and trademarks belong to their respective owners. Their mention in this document is purely for descriptive purposes to identify the data source and does not imply endorsement, affiliation, or partnership.

### Disclaimer

This Actor is an independent collection tool and is not affiliated with or endorsed by Flathub or its maintainers. All data is gathered from standard publicly accessible channels. Users are responsible for adhering to applicable data usage guidelines and software license agreements.

### Is web scraping legal?

This Actor only collects publicly available data, mostly through standard public web feeds and listings without bypassing access controls. Collecting public data is widely practiced, though user responsibilities depend on usage:

- **Personal Data**: If output data contains personal details, regional privacy laws (such as GDPR or CCPA) may apply. Ensure you handle personal identifiers in compliance with local rules.
- **Copyright**: Certain descriptions or software branding may be protected by copyright. Avoid directly republishing copyright-protected content at scale without permission.
- **Terms & Rules**: Ensure your data gathering respects standard rate limits and reasonable web etiquette.

To learn more, read Apify's guide: [Is web scraping legal?](https://blog.apify.com/is-web-scraping-legal/)

# Actor input Schema

## `mode` (type: `string`):

app loads one Flatpak app from GET /api/v2/appstream/{appId}. search posts {query, page} to /api/v2/search. stats loads GET /api/v2/stats/{appId}.

## `query` (type: `string`):

Search text for search mode. Sent as JSON {query} to POST https://flathub.org/api/v2/search. Example: editor.

## `appIds` (type: `array`):

Flatpak app ids for app and stats modes, one per line. Example: org.mozilla.firefox.

## `includeStats` (type: `boolean`):

After an app or search row, also GET /api/v2/stats/{appId} and copy installs_total and installs_last_month. Ignored in stats mode, which already reads that endpoint.

## `requestDelaySecs` (type: `number`):

Seconds to wait before each request. A short burst of the public endpoints returned 2xx with no rate-limit headers, and the actor still waits. Default is 1 request at a time.

## `userAgent` (type: `string`):

User-Agent sent on every request. Include an app name and a contact so the host can identify the client.

## `timeoutSecs` (type: `integer`):

Stop the run after this many seconds and keep rows already collected. Default 300. Maximum 3600.

## `requestTimeoutSecs` (type: `integer`):

How long to wait for one response before treating that call as failed. Default 30 seconds.

## `proxyConfiguration` (type: `object`):

Optional proxy for Flathub requests. Leave useApifyProxy off. The public Flathub API does not need a proxy.

## Actor input object example

```json
{
  "mode": "app",
  "query": "editor",
  "appIds": [
    "org.mozilla.firefox"
  ],
  "includeStats": true,
  "requestDelaySecs": 1,
  "userAgent": "",
  "timeoutSecs": 300,
  "requestTimeoutSecs": 30,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `overview` (type: `string`):

App id, name, summary, developer, license, category, verification, last-month installs, and source URL.

## `errors` (type: `string`):

Failed requests with URL, HTTP status, and message.

## `dataset` (type: `string`):

Every row from the run, without a table view applied.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "editor",
    "appIds": [
        "org.mozilla.firefox"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("kawsar/flathub-apps-scraper").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "query": "editor",
    "appIds": ["org.mozilla.firefox"],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("kawsar/flathub-apps-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "editor",
  "appIds": [
    "org.mozilla.firefox"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call kawsar/flathub-apps-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kawsar/flathub-apps-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/hCxKUmxbz0wFSifPF/builds/ekW67Tjl81a6pvgxD/openapi.json