# X / Twitter Profile Scraper (`simoit/x-twitter-profile-scrapper`) Actor

Collect posts from a specific X profile and build a clear picture of how that account communicates.

- **URL**: https://apify.com/simoit/x-twitter-profile-scrapper.md
- **Developed by:** [simoit](https://apify.com/simoit) (community)
- **Categories:** Social media, Developer tools, Lead generation
- **Stats:** 32 total users, 9 monthly users, 99.1% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.15 / 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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## X Twitter Profile Scraper

![SIMO IT logo](https://simoit.tech/favicon.ico)

Scrape posts from X/Twitter profiles by handle or profile URL. Use it to monitor company accounts, audit executives, research creators, and export profile timelines with keyword, date, reply, and retweet filters.

### Features

- scrape tweets from one or many X/Twitter profiles
- use handles, profile URLs, comma-separated lists, or newline-separated batches
- filter profile timelines by keyword, exact phrase, excluded terms, hashtags, language, and date range
- include or exclude replies, retweets, and pinned tweets
- collect larger exports with `maxItems`; the Actor automatically expands effective pages when needed
- export structured tweet data for audits, BI dashboards, reports, and monitoring workflows

### Use Cases

- competitor account monitoring
- executive and founder content audits
- brand publishing reports
- influencer and creator research
- profile-level keyword tracking
- owned social media archive exports

### How To Use

1. Add a `username`, `usernames`, `profileUrl`, or `profileUrls`.
2. Optionally add filters such as `searchTerms`, `hashtags`, `startDate`, or `endDate`.
3. Set `limit` to `100` for larger exports and choose the desired `maxItems`.
4. Run the Actor and download the dataset.

For most exports, keep `page` at `1`. If you set `maxItems` higher than one page can return, the Actor calculates the needed effective `maxPages` automatically.

### Input

- `username` (string, optional): Single target X username without `@`.
- `usernames` (string, optional): Batch usernames, comma-separated or one per line.
- `profileUrl` (string, optional): Single X/Twitter profile URL.
- `profileUrls` (string, optional): Batch X/Twitter profile URLs, comma-separated or one per line.
- `rawQuery` (string, optional): Advanced X query string used as-is. If provided, it overrides the composed profile query.
- `searchTerms` (string, optional): Keyword filter within profile tweets.
- `exactPhrase` (string, optional): Exact phrase filter.
- `excludeTerms` (string, optional): Terms to exclude, comma-separated.
- `hashtags` (string, optional): Hashtags to require, comma-separated.
- `language` (string, optional): Language filter, such as `en`.
- `sort` (string, optional, default: `latest`): `latest` or `top`.
- `startDate` (string, optional): Start date. Accepts `YYYY-MM-DD`, `D/M/YYYY`, or `M/D/YYYY`.
- `endDate` (string, optional): End date. Accepts `YYYY-MM-DD`, `D/M/YYYY`, or `M/D/YYYY`.
- `since` (string, optional): Alias for `startDate`.
- `until` (string, optional): Alias for `endDate`.
- `includeReplies` (boolean, optional, default: `false`): Include profile replies.
- `includeRetweets` (boolean, optional, default: `false`): Include retweets.
- `includePinned` (boolean, optional, default: `false`): Include the pinned tweet when available.
- `page` (integer, optional, default: `1`): Starting page number. Keep this at `1` for most runs.
- `limit` (integer, optional, default: `20`, max: `100`): Records per page.
- `maxPages` (integer, optional, default: `1`): Minimum pages to fetch. The Actor raises the effective value when `maxItems` needs more pages.
- `maxItems` (integer, optional): Maximum number of output records.

At least one profile target is required: `username`, `usernames`, `profileUrl`, or `profileUrls`.

### Example Input

```json
{
  "profileUrls": "https://x.com/openai, https://x.com/apify",
  "sort": "latest",
  "includeReplies": false,
  "includeRetweets": false,
  "page": 1,
  "limit": 100,
  "maxItems": 200
}
```

### Keyword Monitoring Input

```json
{
  "username": "openai",
  "searchTerms": "gpt OR model OR api",
  "sort": "latest",
  "includeReplies": true,
  "includeRetweets": false,
  "page": 1,
  "limit": 100,
  "maxItems": 200
}
```

### Example Output

```json
{
  "id": 1891009988776655400,
  "id_str": "1891009988776655400",
  "url": "https://x.com/openai/status/1891009988776655400",
  "date": "2026-02-18T14:22:00+00:00",
  "lang": "en",
  "rawContent": "Model update notes and release details.",
  "replyCount": 27,
  "retweetCount": 180,
  "likeCount": 940,
  "quoteCount": 11,
  "conversationId": 1891009988776655400,
  "conversationIdStr": "1891009988776655400",
  "hashtags": ["GPT"],
  "cashtags": [],
  "mentionedUsers": [],
  "links": [],
  "user": {
    "id": 4398626122,
    "id_str": "4398626122",
    "url": "https://x.com/openai",
    "username": "openai",
    "displayname": "OpenAI",
    "verified": true
  },
  "media": {
    "photos": [],
    "videos": [],
    "animated": []
  },
  "_type": "snscrape.modules.twitter.Tweet"
}
```

### Task Presets

See [TASK\_PRESETS.md](./TASK_PRESETS.md) for ready-to-create Apify tasks with names, service descriptions, and copy-paste JSON inputs.

### FAQ

### Pay-per-event billing

When Pay-per-event monetization is enabled for the Actor, each requested profile is classified and charged after filtering:

- `profile-lookup-no-data`: the profile returned 0 records;
- `profile-lookup-low-data`: the profile returned 1–9 records;
- `profile-lookup`: the profile returned 10 or more records.

The minimum billable amount for every profile is 10 record units. Therefore an empty profile and a profile with fewer than 10 records are both charged as 10 units. A profile with 14 records is charged as 14 units. This minimum applies even when the requested profile has no public posts matching the selected filters.

**Why did `maxItems: 200` return only 20 items before?**\
Older inputs often left `limit` and `maxPages` at one page. This Actor now expands effective `maxPages` from `maxItems` and `limit`, so `limit: 100` with `maxItems: 200` can request two pages automatically.

**Should I set a high `page` value?**\
Usually no. Keep `page: 1`, set `limit: 100`, and control the total export with `maxItems`.

**Can I scrape multiple profiles in one run?**\
Yes. Use `usernames` or `profileUrls` with comma-separated or newline-separated values.

**Can I filter one profile by topic?**\
Yes. Use `searchTerms`, `exactPhrase`, `excludeTerms`, `hashtags`, or `language`.

### Related Actors

- Need topic search across all of X, not one profile timeline? Use [Tweet Scraper](https://apify.com/simoit/x-twitter-search-tweets-scrapper).
- Need profile metadata, followers, or following instead of posts? Use [User Scraper](https://apify.com/simoit/x-twitter-user-scrapper).
- Need curated monitoring across multiple accounts grouped in one list? Use [List Scraper](https://apify.com/simoit/x-twitter-list-scraper).
- Need live trend discovery before checking specific profiles? Use [Trends Scraper](https://apify.com/simoit/x-twitter-preset-trends-scrapper) or [Global Trending Scraper](https://apify.com/simoit/x-twitter-trends-scrapper).

Need custom limits, reporting, or a tailored workflow? Contact `contact@simoit.tech`.

# Actor input Schema

## `username` (type: `string`):

X username without @.

## `usernames` (type: `string`):

Optional usernames (comma-separated or new lines).

## `profileUrl` (type: `string`):

Single x.com/twitter.com profile URL.

## `profileUrls` (type: `string`):

Optional x.com/twitter.com profile URLs (comma-separated or new lines).

## `rawQuery` (type: `string`):

Advanced X query string used as-is. If provided, it overrides the composed profile search query.

## `searchTerms` (type: `string`):

Additional keyword filter.

## `exactPhrase` (type: `string`):

Exact phrase emitted as a quoted Twitter search phrase.

## `excludeTerms` (type: `string`):

CSV terms to exclude, emitted as -term operators.

## `hashtags` (type: `string`):

CSV hashtags, emitted as #tag operators.

## `language` (type: `string`):

Language filter, emitted as lang:xx.

## `sort` (type: `string`):

Result sorting mode.

## `startDate` (type: `string`):

Start date. Accepts YYYY-MM-DD, D/M/YYYY, or M/D/YYYY and is normalized automatically.

## `endDate` (type: `string`):

End date. Accepts YYYY-MM-DD, D/M/YYYY, or M/D/YYYY and is normalized automatically.

## `since` (type: `string`):

Alias for start date. Accepts YYYY-MM-DD, D/M/YYYY, or M/D/YYYY.

## `until` (type: `string`):

Alias for end date. Accepts YYYY-MM-DD, D/M/YYYY, or M/D/YYYY.

## `includeReplies` (type: `boolean`):

Include profile replies in the output.

## `includeRetweets` (type: `boolean`):

Include retweets in the output.

## `includePinned` (type: `boolean`):

Include the profile's pinned tweet when available.

## `page` (type: `integer`):

Starting page number. Keep this at 1 for most runs. Starting from a deep page can be slow and may return no data if the profile has fewer matching posts at that depth. Use maxItems and maxPages to collect more results.

## `limit` (type: `integer`):

Items per page.

## `maxPages` (type: `integer`):

Minimum number of pages to fetch starting from Page. If Max items needs more pages, the Actor automatically increases the effective page count.

## `maxItems` (type: `integer`):

Maximum number of output items to push.

## Actor input object example

```json
{
  "username": "openai",
  "searchTerms": "",
  "sort": "latest",
  "includeReplies": false,
  "includeRetweets": false,
  "includePinned": false,
  "page": 1,
  "limit": 10,
  "maxPages": 1,
  "maxItems": 10
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `runReport` (type: `string`):

No description

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

// Prepare Actor input
const input = {
    "username": "openai",
    "limit": 10,
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("simoit/x-twitter-profile-scrapper").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 = {
    "username": "openai",
    "limit": 10,
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("simoit/x-twitter-profile-scrapper").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 '{
  "username": "openai",
  "limit": 10,
  "maxItems": 10
}' |
apify call simoit/x-twitter-profile-scrapper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=simoit/x-twitter-profile-scrapper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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