# LinkedIn Agent (`apexronin/linkedin-agent`) Actor

A linkedin agent

- **URL**: https://apify.com/apexronin/linkedin-agent.md
- **Developed by:** [Jensin](https://apify.com/apexronin) (community)
- **Categories:** Agents, Social media, Automation
- **Stats:** 32 total users, 0 monthly users, 100.0% runs succeeded, 4 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

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

## 🚀 LinkedIn Agent - Clean Architecture

A production-ready LinkedIn scraping agent with a clean, organized architecture. This project has been restructured for better maintainability, scalability, and developer experience.

### 🏗️ Project Structure

```
linkedin-agent/
├── 📁 backend/                    # Core LinkedIn scraping engine
│   ├── src/                      # Main Python source code
│   ├── tests/                    # Backend tests
│   ├── requirements.txt          # Python dependencies
│   └── Dockerfile*              # Backend containers
├── 📁 frontend/                  # React admin dashboard
│   ├── src/                     # React components
│   └── package.json             # Frontend dependencies
├── 📁 infrastructure/            # Deployment & DevOps
│   ├── docker/                  # Docker configurations
│   ├── scripts/                 # Utility scripts
│   └── monitoring/              # Monitoring configs
├── 📁 docs/                      # Documentation
├── 📁 examples/                  # Sample inputs & configs
└── 📁 storage/                   # Runtime data (gitignored)
```

### 🚀 Quick Start

#### 1. Setup Development Environment

```bash
## Clone and setup
git clone <your-repo>
cd linkedin-agent
make setup-dev

## Edit environment variables
nano .env  # Add your API keys

## Start development
make dev
```

#### 2. Setup Production Environment

```bash
## Setup production
make setup-prod

## Edit production settings
nano .env

## Deploy
make deploy
```

### ✨ Key Features

- **🎯 Clean Architecture**: Separated backend, frontend, and infrastructure
- **🐳 Docker-First**: Multi-stage builds with development and production configs
- **📊 Queue Processing**: Redis-based job queue with worker processes
- **🔒 Security**: JWT authentication and role-based access
- **📈 Monitoring**: Health checks and Prometheus integration
- **💾 Persistent Storage**: SQLite database with backup automation
- **🔄 Batch Processing**: Excel/CSV input with resumable processing
- **🎨 Modern UI**: React-based admin dashboard

### 🛠️ Development Commands

```bash
## Show all available commands
make help

## Backend development
make dev                    # Start backend services
make backend-test          # Run backend tests
make backend-lint          # Run backend linting

## Frontend development
make frontend-dev          # Start frontend development
make frontend-test         # Run frontend tests
make frontend-lint         # Run frontend linting

## Full stack development
make fullstack-dev         # Start both backend and frontend

## Production
make deploy                # Deploy to production
make stop                  # Stop all services
make clean                 # Clean up containers

## Utilities
make status                # Check service status
make logs                  # View service logs
make backup                # Create backup
make health                # Health check
```

### 📚 Documentation

- **[Project Structure](PROJECT_STRUCTURE.md)** - Detailed structure guide
- **[Architecture](docs/ARCHITECTURE.md)** - System design and components
- **[API Documentation](docs/API.md)** - REST API reference
- **[Deployment](docs/DEPLOYMENT.md)** - Production deployment guide
- **[Development](docs/DEVELOPMENT.md)** - Development workflow

### 🔧 Configuration

#### Environment Variables

Copy the example environment file and configure:

```bash
cp examples/env.example .env
```

Key variables:

- `OPENAI_API_KEY` - OpenAI API key for LLM features
- `APIFY_TOKEN` - Apify token for proxy and platform features
- `SUPABASE_JWT_SECRET` - JWT secret for authentication

#### Input Formats

The system supports multiple input formats:

1. **JSON Input**: Direct LinkedIn URLs
2. **CSV/Excel**: Batch processing with LinkedIn URLs
3. **REST API**: Programmatic job submission

##### Excel Templates

For Excel batch processing, use the provided templates:

- **`examples/linkedin_template.xlsx`** - Empty template with correct structure
- **`examples/sample_input.xlsx`** - Example data showing proper format

Excel files must have tabs named:

- `Company_Profiles` - For LinkedIn company pages
- `Individual_Profiles` - For LinkedIn personal profiles

See `docs/EXCEL_FORMAT.md` for detailed format requirements.

See `examples/` directory for sample inputs.

### 🚦 Usage Examples

#### CLI Mode

```bash
cd backend
python -m src.cli ../examples/input.json
```

#### REST API

```bash
## Submit job
curl -F "owner_email=user@example.com" \
     -F "input_file=@examples/input.csv" \
     http://localhost:8000/submit

## Check status
curl http://localhost:8000/status/1

## Download results
curl -OJ http://localhost:8000/result/1
```

#### Batch Processing

```bash
cd backend

## Enhanced processor with multi-tab support and URL validation
./src/batch_scrape_excel_enhanced.sh ../examples/sample_input.xlsx ../examples/input.json

## Legacy processor (single sheet only)
./src/batch_scrape_excel.sh ../examples/sample_input.xlsx ../examples/input.json
```

### 🏗️ Architecture Overview

#### Backend Components

- **API Server**: FastAPI REST API for job management
- **Worker**: Queue processing with Redis
- **Crawler**: Playwright-based LinkedIn scraping
- **Database**: SQLite for job persistence
- **Agent**: LLM orchestration for summarization

#### Frontend Components

- **Admin Dashboard**: React-based management interface
- **Authentication**: Supabase-based auth with role management
- **Real-time Updates**: WebSocket integration for job status

#### Infrastructure

- **Docker**: Multi-stage builds for development and production
- **Monitoring**: Prometheus and health checks
- **Backup**: Automated backup system
- **CI/CD**: Ready for pipeline integration

### 🔒 Security

- **Authentication**: JWT-based authentication with Supabase
- **Authorization**: Role-based access control (admin/user)
- **Input Validation**: Comprehensive input sanitization
- **Container Security**: Non-root user execution
- **Network Security**: Internal service communication

### 📊 Monitoring & Health

#### Health Endpoints

- `/health` - Full system health check
- `/health/simple` - Simple health check
- `/health/ready` - Kubernetes readiness probe
- `/health/live` - Kubernetes liveness probe

#### Monitoring

- **Prometheus**: Metrics collection
- **Grafana**: Dashboard (optional)
- **Logs**: Structured logging with rotation

### 🚀 Deployment

#### Development

```bash
make setup-dev
make dev
```

#### Production

```bash
make setup-prod
make deploy
```

#### Docker Compose

```bash
## Development
cd infrastructure/docker
docker-compose up -d

## Production
docker-compose -f docker-compose.prod.yml up -d
```

### 🤝 Contributing

1. **Fork** the repository
2. **Create** a feature branch
3. **Make** your changes
4. **Test** thoroughly
5. **Submit** a pull request

#### Development Workflow

```bash
## Setup development environment
make setup-dev

## Make changes in backend/src/ or frontend/src/

## Test your changes
make backend-test
make frontend-test

## Format code
make backend-lint
make frontend-lint

## Commit and push
git add .
git commit -m "feat: your feature description"
git push origin feature/your-feature
```

### 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

### 🆘 Support

- **Documentation**: Check the `docs/` directory
- **Examples**: See `examples/` directory for usage examples
- **Issues**: Report bugs and feature requests via GitHub issues

***

**🎉 Welcome to the clean, organized LinkedIn Agent!**

This restructured project makes development, deployment, and maintenance much easier. The separation of concerns and clear documentation will help you get up and running quickly.

# Actor input Schema

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

Text query to search for contact details and potentially deduplicate them.

## `modelName` (type: `string`):

Specify the LLM for orchestration and summarization. Currently supports OpenAI models with varying capabilities and performance.

## `summarizeResults` (type: `boolean`):

Generate a short summary of the scraped contact details

## Actor input object example

```json
{
  "query": "I would like to get contact details from apify.com",
  "modelName": "gpt-4o",
  "summarizeResults": false
}
```

# 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": "I would like to get contact details from apify.com"
};

// Run the Actor and wait for it to finish
const run = await client.actor("apexronin/linkedin-agent").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": "I would like to get contact details from apify.com" }

# Run the Actor and wait for it to finish
run = client.actor("apexronin/linkedin-agent").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": "I would like to get contact details from apify.com"
}' |
apify call apexronin/linkedin-agent --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apexronin/linkedin-agent"
        }
    }
}

```

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/TCTppZhgbHcRAUtp0/builds/hdAm9BSrfFD1ROnQn/openapi.json