Get social media data over an API

Every tool on CIA has a matching API route under /api/v1, authenticated with your API key. Credits are deducted before the system fetches data, and if the provider fails a reversing entry is written. This page is about calling it, and about the boundaries the API has to respect too.

Where to start

You have not called it yet. Read getting started with the API.

You are worried about being charged twice. Read what Idempotency-Key does. Read this before you write your first retry loop.

You do not write code. Read getting data into Google Sheets.

You want to know the boundaries. Read what public data means and Decree 13/2023 for marketers.

Three things about billing

Charge first, refund after. Credits are deducted before the call. If the provider fails and you get nothing usable, the system writes a reversing entry. Every movement is one row in a ledger with the balance after it — nothing changes a balance without leaving a trace.

Prices are per module and come from configuration. Each tool's price lives in the product table and an administrator can change it, so do not hard-code the number in your code. See pricing.

There are no shortcuts. There is no way to run a tool without going through that tool's runner, including over the API. That protects both sides.

Boundaries the API respects too

The API returns no email addresses, no personal phone numbers, and there is no endpoint that returns a list of people to contact. Phone numbers appear only for businesses in directories such as Google Maps, because that is the business's own public line.

An account that has submitted a block request at the data request page is refused before credits are charged — over the web and over the API alike.

Frequently asked questions

Is there an unlimited plan? No. Everything is charged in credits, and every tool has a hard limit per run. See the limits on each feature page.

What happens if I repeat a successful request? If you resend the same Idempotency-Key, the system returns the earlier result and does not charge again. Change the key and it is a new run, charged as such.

Is the data official platform analytics? No. It is an estimate from public data the platform displays to everyone.