API v1Research Plan

Dokumentasi SocialX API

Ambil data dari berbagai sumber langsung dari aplikasi atau script kamu. Kirim job lewat API, pantau statusnya, lalu unduh hasilnya dalam format JSON atau CSV.

Base URLhttps://www.socialx.id/api/ext/v1

Pendahuluan

Job yang dikirim lewat API diproses oleh mesin yang sama dengan Studio: antreannya satu, hasilnya pun otomatis muncul di halaman Riwayat Data di Studio.

API tersedia untuk pengguna Research Plan. Mulainya cukup tiga langkah:

Buat API key

Sekali saja, dari halaman Akun. Key digunakan pada header setiap request.

Kirim job

POST /jobs dengan sumber, nama job, dan config-nya. Job langsung masuk antrean.

Ambil hasilnya

Pantau status job, lalu unduh hasilnya dalam format JSON atau CSV.

Autentikasi

Semua request menggunakan header X-API-Key. Buat key di halaman Akun › API. Key hanya ditampilkan sekali saat dibuat, jadi simpan dengan aman. Maksimal 5 key aktif per akun; key dapat dicabut kapan saja.

curl https://www.socialx.id/api/ext/v1/me \
  -H "X-API-Key: sx_live_xxxxxxxxxxxxxxxxxxxx"

Jaga kerahasiaan key. Jangan taruh key di kode frontend, repo publik, atau notebook yang dibagikan. Kalau bocor, cabut dari halaman Akun › API lalu buat yang baru.

Batas Pemakaian

Batas	Nilai	Keterangan
Request	60 / menit / key	Berlaku untuk semua endpoint.
Job baru	20 / hari / akun	Jendela bergulir 24 jam. Hanya job yang berhasil dibuat yang dihitung.
Job aktif	1 pada satu waktu	Dihitung bersama job dari Studio. Jika masih ada job yang berjalan, request akan dijawab dengan status 409.
Data per job	2.500 / 5.000 / 10.000	Mengikuti paket Research Plan kamu (Standard, Pro, atau Max).

Lewat batas, request dijawab 429 dengan header Retry-After.

Status Job

Status	Arti
running	Masih antre atau sedang diproses.
done	Selesai. data_count memuat jumlah baris; nol tetap valid kalau memang tidak ada data yang cocok.
stopped	Dihentikan lewat endpoint stop atau tombol stop di Studio.
failed	Berhenti karena kendala di mesin. Coba kirim ulang; kalau berulang, hubungi kami.

Pantau status job dengan polling ke GET /jobs/:id setiap 15-30 detik. Jika config job sama dengan job yang berjalan dalam 1 jam terakhir, hasilnya dapat disajikan dari cache sehingga selesai lebih cepat.

Format Error

Error dijawab dengan HTTP status yang sesuai. Body respons berisi message yang mudah dibaca dan data.code yang stabil untuk ditangani oleh program.

{
  "statusCode": 403,
  "message": "API hanya tersedia untuk pengguna Research Plan.",
  "data": { "code": "plan_required" }
}

HTTP	Kode	Kapan terjadi
400	validation_error	Body atau config tidak valid. Detail per field ada di data.fields.
400	unknown_source	Slug sumber tidak dikenal atau belum tersedia lewat API.
401	missing_api_key	Header X-API-Key tidak ada.
401	invalid_api_key	Key tidak dikenal atau sudah dicabut.
403	plan_required	Akun bukan Research Plan aktif.
403	source_unavailable	Sumber sedang dalam perbaikan.
403	max_data_exceeded	maxData melebihi batas paket.
404	not_found	Job tidak ditemukan atau bukan milik kamu.
409	job_in_progress	Masih ada job aktif. ID job yang sedang berjalan tersedia di data.running_job_id.
409	not_running	Job tidak sedang running.
429	rate_limited	Lebih dari 60 request dalam semenit.
429	daily_quota_exceeded	Kuota 20 job per hari habis.

GET/sources

Katalog sumber

Daftar sumber yang tersedia lewat API beserta skema parameternya. Sumber yang sedang dalam perbaikan otomatis hilang dari daftar.

Contoh request

curl https://www.socialx.id/api/ext/v1/sources \
  -H "X-API-Key: sx_live_..."

Contoh response

{
  "success": true,
  "data": {
    "sources": [
      {
        "slug": "twitter",
        "name": "Twitter",
        "description": "Ambil tweet berdasarkan kata kunci, profil, atau tautan tweet",
        "params": { "mode": "...", "keywords": "...", "maxData": "..." }
      }
    ]
  }
}

POST/jobs

Kirim job

Buat job baru untuk mengambil data. Job langsung masuk antrean dan diproses oleh mesin yang sama seperti di Studio. Struktur config berbeda untuk setiap sumber, lihat Referensi Sumber Data.

Parameter

Nama	Letak	Keterangan
source*	body	Slug sumber, misalnya twitter atau kompas. Lihat GET /sources.
job_name*	body	Nama job, 3-100 karakter. Tampil juga di Riwayat Data Studio.
config*	body	Objek config sesuai skema sumber.
tags	body	Array berisi maksimal 1 string penanda job.

Contoh request

curl -X POST https://www.socialx.id/api/ext/v1/jobs \
  -H "X-API-Key: sx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source": "twitter",
    "job_name": "monitoring brand juli",
    "config": {
      "mode": "keyword",
      "keywords": "indomie",
      "startDate": "2026-06-01",
      "endDate": "2026-07-01",
      "maxData": 500
    }
  }'

Contoh response

{
  "success": true,
  "data": {
    "job": {
      "id": "3f6b2c1e-...",
      "source": "twitter",
      "job_name": "monitoring brand juli",
      "status": "running",
      "tags": [],
      "max_data": 500,
      "created_at": "2026-07-13T04:20:11.000Z"
    }
  },
  "message": "Job berhasil dibuat dan masuk antrean."
}

GET/jobs

Daftar job

Daftar job milik kamu, terbaru lebih dulu. Job dari Studio ikut tampil karena antreannya satu.

Parameter

Nama	Letak	Keterangan
status	query	Saring status: running, done, stopped, atau failed.
source	query	Saring berdasarkan slug sumber.
page	query	Halaman, mulai dari 1.
limit	query	Jumlah per halaman, default 20, maksimal 100.

Contoh request

curl "https://www.socialx.id/api/ext/v1/jobs?status=done&limit=5" \
  -H "X-API-Key: sx_live_..."

Contoh response

{
  "success": true,
  "data": {
    "jobs": [
      {
        "id": "3f6b2c1e-...",
        "source": "twitter",
        "job_name": "monitoring brand juli",
        "status": "done",
        "tags": [],
        "data_count": 500,
        "created_at": "2026-07-13T04:20:11.000Z",
        "finished_at": "2026-07-13T04:26:40.000Z"
      }
    ],
    "pagination": { "page": 1, "limit": 5, "total": 12, "total_pages": 3 }
  }
}

GET/jobs/:id

Detail job

Status dan metadata satu job. Polling endpoint ini sampai statusnya done.

Parameter

Nama	Letak	Keterangan
id*	path	Id job dari response submit.

Contoh request

curl https://www.socialx.id/api/ext/v1/jobs/3f6b2c1e-... \
  -H "X-API-Key: sx_live_..."

Contoh response

{
  "success": true,
  "data": {
    "job": {
      "id": "3f6b2c1e-...",
      "source": "twitter",
      "job_name": "monitoring brand juli",
      "status": "done",
      "error_code": null,
      "tags": [],
      "data_count": 500,
      "config": { "mode": "keyword", "keywords": "indomie", "maxData": 500 },
      "created_at": "2026-07-13T04:20:11.000Z",
      "finished_at": "2026-07-13T04:26:40.000Z"
    }
  }
}

GET/jobs/:id/data

Intip hasil

Lihat sebagian hasil dengan paginasi, maksimal 1.000 baris pertama. Untuk seluruh data, pakai endpoint export.

Parameter

Nama	Letak	Keterangan
id*	path	Id job.
page	query	Halaman, mulai dari 1.
limit	query	Jumlah per halaman, default 50, maksimal 200.

Contoh request

curl "https://www.socialx.id/api/ext/v1/jobs/3f6b2c1e-.../data?limit=100" \
  -H "X-API-Key: sx_live_..."

Contoh response

{
  "success": true,
  "data": {
    "job": { "id": "3f6b2c1e-...", "source": "twitter", "status": "done", "data_count": 500 },
    "rows": [ { "...": "..." } ],
    "pagination": { "page": 1, "limit": 100, "total": 500, "peekable": 500, "total_pages": 5 }
  }
}

GET/jobs/:id/export

Export penuh

Unduh seluruh hasil job sekali baca, tanpa batas baris. Format CSV dikirim sebagai file dan aman dibuka langsung di Excel atau dibaca pandas.

Parameter

Nama	Letak	Keterangan
id*	path	Id job.
format	query	json (default) atau csv.

Contoh request

curl "https://www.socialx.id/api/ext/v1/jobs/3f6b2c1e-.../export?format=csv" \
  -H "X-API-Key: sx_live_..." -o hasil.csv

Contoh response

{
  "success": true,
  "data": {
    "job": { "id": "3f6b2c1e-...", "source": "twitter", "status": "done", "data_count": 500 },
    "rows": [ { "...": "..." } ]
  }
}

POST/jobs/:id/stop

Hentikan job

Hentikan job yang sedang running. Job yang berhenti berstatus stopped dan tidak bisa dilanjutkan.

Parameter

Nama	Letak	Keterangan
id*	path	Id job.

Contoh request

curl -X POST https://www.socialx.id/api/ext/v1/jobs/3f6b2c1e-.../stop \
  -H "X-API-Key: sx_live_..."

Contoh response

{
  "success": true,
  "data": {
    "job": { "id": "3f6b2c1e-...", "status": "stopped", "finished_at": "2026-07-13T04:23:05.000Z" }
  },
  "message": "Job dihentikan."
}

GET/me

Info akun

Email, paket, jumlah job aktif, dan sisa kuota harian pemegang key. Gunakan endpoint ini untuk mengecek koneksi dan sisa kuota sebelum mengirim job.

Contoh request

curl https://www.socialx.id/api/ext/v1/me \
  -H "X-API-Key: sx_live_..."

Contoh response

{
  "success": true,
  "data": {
    "email": "kamu@kampus.ac.id",
    "tier": "unlimited_pro",
    "active_jobs": 0,
    "daily_job_quota": { "limit": 20, "remaining": 18 }
  }
}

Referensi Sumber Data

Nilai source dan struktur config berbeda untuk setiap sumber. Daftar di bawah selalu mengikuti katalog terbaru; kamu juga dapat mengambil versinya lewat GET /sources.

Memuat daftar sumber...

Mulai dalam hitungan menit

Buat API key dari halaman Akun, kirim job pertama, lalu ambil hasilnya lewat API. Semua fitur tersedia untuk pengguna Research Plan.

Buat API Key Lihat Research Plan