Skip to main content

QuickStart

This example generates Instagram followers without a collection or input rows. It can consume Datablist credits. Replace the sample profile with a profile you want to query.

Authentication​

Create a Personal API Key from the API page in your Datablist account, then exchange it for a 24-hour access token:

bash
curl --request POST 'https://api.datablist.com/v1/account/token' \
  --header 'Content-Type: application/json' \
  --data '{"apiKey":"YOUR_PERSONAL_API_KEY"}'

See Get an access token for the request field, response attributes, and error statuses.

The response contains the token and its expiration:

json
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "expires_at": 1791622800,
  "account_id": "account-id",
  "user_id": "user-id",
  "plan": "business",
  "scope": ["admin"]
}

Send access_token on every authenticated request:

http
Authorization: Bearer ACCESS_TOKEN

The account-bound token expires after 24 hours. Exchange the Personal API Key again after expiration. Deleting the key prevents future exchanges but does not revoke tokens that have already been issued.

Keep the key private. Use the access token, not the key, in the Bearer header. Never include either credential in task data or logs. You can access only tasks belonging to the token's account.

Try a request in the documentation​

Open Try it on an endpoint page. Choose Personal API Key, paste your key, and click Connect. You can also choose Access token to use a token you already have. The key is cleared after exchange. Authentication stays in memory while you navigate the documentation; refreshing the page or clicking Disconnect clears it. Connect again after the token expires or a request returns 401.

Fill in your IDs and review the parameters and JSON body, then click Send. The response panel shows the status, body, headers, and request duration. These are real API calls: tasks can consume credits, and writes or deletions change your data.

Closing the panel or clicking Cancel request stops waiting in your browser. It cannot undo work already accepted by the API. Check task status yourself; the documentation does not retry requests or check progress automatically.

Previous calls stay available in the panel so you can find earlier IDs and responses. Disconnect clears your credentials and call history.

1. Discover the source​

Catalog discovery requires no authentication. Use the returned access_token for task creation and subsequent task operations.

bash
curl 'https://api.datablist.com/v1/sources'


curl 'https://api.datablist.com/v1/sources/instagram-source'

Confirm the source is available, then inspect settingsSchema, outputSchema, and limits.

2. Create a task​

bash
curl --request POST 'https://api.datablist.com/v1/sources/tasks' \
  --header 'Authorization: Bearer DATABLIST_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "sourceId": "instagram-source",
    "uniqueId": "instagram-followers-example",
    "settings": {
      "profiles": "example_profile",
      "scrapingType": "followers",
      "limitPerProfile": 100
    }
  }'

The API returns 202 Accepted. Save the task @id, links.self, and links.results. The requested limit is not a guarantee of an exact result count. Omit maxCredits for no task-specific budget, or use a nonnegative decimal string for a best-effort credit limit.

3. Check task status​

bash
curl 'https://api.datablist.com/v1/sources/tasks/TASK_ID' \
  --header 'Authorization: Bearer DATABLIST_ACCESS_TOKEN'

Poll every few seconds until status is completed, failed, or stopped. The response shows how many objects have been generated, the credits used, and an error if the task failed.

4. Retrieve every result page​

bash
curl 'https://api.datablist.com/v1/sources/tasks/TASK_ID/results?limit=50' \
  --header 'Authorization: Bearer DATABLIST_ACCESS_TOKEN'

Results contain flat JSON objects. If nextCursor is not null, request the next page, passing the cursor unchanged:

bash
curl --get 'https://api.datablist.com/v1/sources/tasks/TASK_ID/results' \
  --header 'Authorization: Bearer DATABLIST_ACCESS_TOKEN' \
  --data-urlencode 'limit=50' \
  --data-urlencode 'cursor=NEXT_CURSOR'

Read results from failed or stopped tasks too; some work may have finished. Requesting results while a task is still active returns 409 ResultsNotReady. See Get tasks results.

Safe retries​

If a creation response is lost, look for your uniqueId in task history before sending another POST. The task may already have run.

An active duplicate returns 409. Once the task finishes or becomes overdue, the same uniqueId can start a new task and consume credits again. Check both source and enrichment histories if you use both APIs. See task lifecycle for cancellation, retention, and shared limits.