API
Being built: limits can still change until this notice goes.
The API gives your organisation programmatic access to the creators list of Social-238, within the quotas of your plan. See Plans.
On this page
Base URL
https://cnxrcnxglvcbwkuqcgdd.supabase.co/functions/v1/creadores-tracker/v1
The host moves with the product's name. We will announce the move before it happens. v1 is the only version. Any other suffix answers 404 with the error version.
Authentication
- Send your key in the header
x-api-key. Keys start withrd_. - There is one key per organisation.
- A key is shown once, when it is created. We keep only its hash.
- A key can be revoked at any time. Write to hello@social238.com.
- Never put a key in a URL.
How a call works
Every call is a POST with a JSON body: {"op": "...", ...}. There are no REST paths and no GET. The key is checked first, then the plan, then the quota, then the operation.
Operations a key may call
| op | What it does |
|---|---|
lista | The list of creators. Filters: search text, network, country, region, place, followers range, apparent age band, has contact. A sort. Pages of up to 50 rows. The rows are previews: no handles and no contact details; those come with detalle. Paging is by keyset cursor (orden~value~id, never an offset): send back the cursor of the last page. The limits of the viewer apply. |
detalle | One creator in full: handles, contact details, history. Each call counts one profile of the month's profile quota. |
conteos | Counts for a filter. |
lugares | The places the list knows. |
estados | The states of the creators. |
leer_pedir | Ask for a fresh read of a handle. |
seguimiento | The handles your organisation tracks, with the latest read of each and your counts. |
seguimiento_poner | Start tracking a handle, or change the cadence of one you track. Takes an optional cadencia. The number of tracked handles is capped by your plan. |
seguimiento_quitar | Stop tracking a handle. |
seguimiento_historia | The daily reads of a handle you track. |
uso | This month's numbers: calls, limit and the reset date. |
The exact filter names and response fields are those of the page's function, creadores-tracker. Read the answers as they are. A key never reaches the states and notes of other users, writes, deletes, admin or internal operations. Any op outside the list answers 403 op_api.
Tracking handles
Each handle you track is read again on a cadence: diaria (about every day) or semanal (about every week). Handles are {"red": "tt" or "ig", "handle": "..."}.
| Plan | Handles | Daily | History |
|---|---|---|---|
| Starter | 50 | none, weekly only | Last 7 days |
| Pro | 300 in all | up to 100 of them | Last 7 days |
| Business | 2,000 | all 2,000 | 90 days of daily rows |
seguimiento answers {"seguimiento": [...], "diarias": n, "semanales": n, "limites": {"handles": n, "diarios": n}}. A limit of null means no limit. Each item is {"red", "handle", "cadencia", "creado", "ultima"}. ultima is the newest read, {"dia", "leido", "datos"}, or null if the handle has not been read yet.
seguimiento_poner takes {"red", "handle", "cadencia"}. Without cadencia the handle is daily while your plan has daily room, and weekly after that. For a handle you already track it changes the cadence and answers "ya": true.
seguimiento_historia takes {"red", "handle", "desde", "hasta", "limite"}. Only red and handle are required; desde and hasta are dates (YYYY-MM-DD) and limite is at most 400. It answers {"red", "handle", "cadencia", "dias": n, "historia": [{"dia", "leido", "datos"}]}, newest first, with one row per UTC day. dias is the window of your plan: 90 on Business, 7 on Starter and Pro.
The datos keys, each one optional and possibly null:
| Key | Meaning |
|---|---|
seguidores, siguiendo | Followers and following. |
publicaciones, likes | Posts and total likes. |
nombre | Display name. |
verificado, privada | Verified and private flags. |
ultimo_post | Date of the latest post. |
estado | ok, no_existe, privada or ilegible. |
Quotas
- Each plan has a monthly number of API calls. See Plans.
- Usage is counted per key, op and day. Only counts are kept, never the request or the answer.
- Over the quota the call is refused. You are never billed over the quota.
- An expired paid plan behaves as Free, which has no API.
Errors
Errors are JSON with an error field.
| Code | Body | Meaning |
|---|---|---|
| 400 | {"error": ...} | Bad request. The answer names the row and field. |
| 401 | {"error": "clave"} | Unknown or revoked key. |
| 403 | {"error": "plan", "plan": ...} | The plan expired or does not include the API. |
| 403 | {"error": "op_api"} | The op is not one a key may call. |
| 403 | {"error": "suprimido"} | The account asked not to be tracked. |
| 404 | {"error": "version"} | The version in the URL does not exist. |
| 404 | {"error": "no_existe"} | Your organisation does not track that handle. |
| 413 | The body is too large. | |
| 429 | {"error": "cuota", "plan", "limite", "usado", "reinicia"} | Monthly quota spent. The header Retry-After gives the seconds until reinicia, the first day of next month. |
| 429 | {"error": "tope"} | Your plan's handle limit is reached. |
| 429 | {"error": "tope_diaria"} | Your plan's daily handles are used up. Add the handle with "cadencia": "semanal". |
| 507 | {"error": "sin_espacio"} | The database is full. Try later. |
| 500, 503 | A fault on our side. Check the status page. |
Example call
curl -X POST \
https://cnxrcnxglvcbwkuqcgdd.supabase.co/functions/v1/creadores-tracker/v1 \
-H "x-api-key: rd_YOUR_KEY" \
-H "content-type: application/json" \
-d '{"op": "uso"}'Track a handle weekly:
curl -X POST \
https://cnxrcnxglvcbwkuqcgdd.supabase.co/functions/v1/creadores-tracker/v1 \
-H "x-api-key: rd_YOUR_KEY" \
-H "content-type: application/json" \
-d '{"op": "seguimiento_poner", "red": "tt", "handle": "someone", "cadencia": "semanal"}'Removal requests
This op needs no key. It lets anyone ask for an account to be removed: {"op": "supresion_pedir", "red": "tt" or "ig", "handle": "...", "motivo": "...", "correo": "..."}. The motivo is at most 1000 characters. The correo is optional. A bad handle answers 400. More than 200 requests a day in all answers 429 muchos. A removed creator leaves every answer within a day. Customers should also honour removals in their own copies. The removal page has a form.
Data terms
You may not resell the data. You may not re-export it in bulk. You must honour removals. The full rules are in the terms and the data agreement.
Support
Write to hello@social238.com. Service state is on the status page.