All API requests require authentication using an API token. You can create and manage tokens in the Settings page.

Using the Token

Include your token in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Or simply:

Authorization: YOUR_TOKEN_HERE

All API endpoints are prefixed with:

https://your-domain.com/api/v1

For local development, use: http://localhost:5000/api/v1

List Jobs

GET /api/v1/jobs

Get a paginated list of all jobs.

Query Parameters:

• page (integer, default: 1) - Page number
• per_page (integer, default: 20) - Items per page
• status (string, optional) - Filter by status (queued, running, finished, failed)

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:5000/api/v1/jobs?page=1&per_page=20"

Example Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Hashtag Scraping",
      "job_type": "hashtag",
      "status": "finished",
      "users_stored": 150,
      "created_at": "2025-12-29T10:00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "pages": 1
  }
}

---

Get Job

GET /api/v1/jobs/{id}

Get details of a specific job.

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:5000/api/v1/jobs/1"

---

Create Job

POST /api/v1/jobs

Create a new scraping job.

Request Body:

{
  "name": "My Scraping Job",
  "job_type": "hashtag",  // hashtag, followers, following, likers
  "speed_mode": "normal",  // safe, normal, aggressive
  "max_leads": 1000,
  "max_leads_per_target": 500,
  "filters": {
    "min_followers": 1000,
    "max_followers": 100000
  },
  "target_ids": [1, 2, 3]
}

Example Request:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fitness Influencers",
    "job_type": "hashtag",
    "target_ids": [1, 2]
  }' \
  "http://localhost:5000/api/v1/jobs"

---

Run Job

POST /api/v1/jobs/{id}/run

Start executing a job.

Example Request:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:5000/api/v1/jobs/1/run"

---

Delete Job

DELETE /api/v1/jobs/{id}

Delete a job.

Example Request:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:5000/api/v1/jobs/1"

List Targets

GET /api/v1/targets

Get a paginated list of all targets.

Query Parameters:

• page (integer, default: 1)
• per_page (integer, default: 20)
• type (string, optional) - Filter by target type

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:5000/api/v1/targets"

---

Get Target

GET /api/v1/targets/{id}

Get details of a specific target.

---

Create Target

POST /api/v1/targets

Create a new target (hashtag, username, etc.).

Request Body:

{
  "identifier": "#fitness",  // or username, post URL, etc.
  "target_type": "hashtag",  // hashtag, followers, following, likers
  "status": "pending"
}

Example Request:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "#fitness",
    "target_type": "hashtag"
  }' \
  "http://localhost:5000/api/v1/targets"

---

Delete Target

DELETE /api/v1/targets/{id}

Delete a target.

List Leads

GET /api/v1/leads

Get a paginated list of all leads.

Query Parameters:

• page (integer, default: 1)
• per_page (integer, default: 20)
• outreach_ready (boolean, optional) - Filter outreach-ready leads
• source_type (string, optional) - Filter by source type

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:5000/api/v1/leads?outreach_ready=true&page=1"

Example Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "username": "fitness_guru",
      "full_name": "Fitness Guru",
      "followers": 50000,
      "emails": "contact@example.com",
      "platform": "instagram"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "pages": 8
  }
}

---

Get Lead

GET /api/v1/leads/{id}

Get details of a specific lead.

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:5000/api/v1/leads/1"

List Content Analysis

GET /api/v1/content-analysis

Get a paginated list of content analysis data.

Query Parameters:

• page (integer, default: 1)
• per_page (integer, default: 20)
• platform (string, optional) - Filter by platform (instagram, tiktok)
• username (string, optional) - Filter by username
• job_id (integer, optional) - Filter by job ID

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:5000/api/v1/content-analysis?platform=instagram&page=1"

Example Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "platform": "instagram",
      "username": "fitness_guru",
      "post_id": "123456789",
      "likes_count": 5000,
      "comments_count": 200,
      "views_count": 10000,
      "engagement_rate": "5.2%"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 50,
    "pages": 3
  }
}

---

Get Content Analysis

GET /api/v1/content-analysis/{id}

Get details of a specific content analysis record.

Get Statistics

GET /api/v1/stats

Get application-wide statistics and your token usage.

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:5000/api/v1/stats"

Example Response:

{
  "success": true,
  "data": {
    "total_leads": 1500,
    "total_jobs": 25,
    "total_targets": 100,
    "total_content_analysis": 500,
    "total_api_requests": 10000,
    "today_api_requests": 150,
    "token_requests": 500,
    "token_last_used": "2025-12-29T16:00:00"
  }
}

The API uses standard HTTP status codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (invalid or missing token)
• 404 - Not Found
• 500 - Internal Server Error

Error Response Format

All errors return a JSON object with an error field:

{
  "error": "Invalid token",
  "message": "The provided API token is invalid"
}

Common Errors

• 401 Unauthorized: Missing or invalid API token
• 400 Bad Request: Missing required fields or invalid data format
• 404 Not Found: Resource doesn't exist

Each API token tracks the total number of requests made. You can view request counts in the Settings page.

Request counts are updated automatically with each API call and include:

• Total requests made with the token
• Last used timestamp

Note: There are no hard rate limits currently, but excessive usage may be monitored.