API Documentation

Complete reference for the Datapio scraping API endpoints.

https://api.datapio.app

Authentication

All API requests require a Bearer token in the Authorization header.

Go to the API Info page to find your API key.
Include the API key in the Authorization header of every request.
Format: Bearer YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Response Format

Every response — success or error — follows the same top-level envelope.

Success

{
  "success": true,
  "data": "...",
  "meta": {
    "requestId": "req_abc123",
    "creditsCharged": 1,
    "creditsRemaining": 999,
    "executionTimeMs": 280,
    "cached": false
  }
}

Field	Type	Description
`success`	true	Always `true` on success.
`data`	object \| array	The endpoint-specific payload. Shape varies per endpoint — see Response Fields below each endpoint.
`meta.requestId`	string	Unique ID for this request. Include in bug reports.
`meta.creditsCharged`	number	Credits deducted for this request. `0` when served from cache.
`meta.creditsRemaining`	number	Credits left in your account after this request.
`meta.executionTimeMs`	number	Server-side processing time in milliseconds.
`meta.cached`	boolean	`true` if the result was served from cache. No credits are charged on cached responses.

Error

{
  "success": false,
  "error": {
    "code": "NO_HEALTHY_SCRAPER",
    "message": "No healthy scraper accounts available",
    "requestId": "req_abc123"
  }
}

Field	Type	Description
`success`	false	Always `false` on error.
`error.code`	string	Machine-readable error code. Stable across API versions — safe to branch on.
`error.message`	string	Human-readable description of the error.
`error.requestId`	string \| undefined	Present when the request reached the server. Include in bug reports.

Rate Limits

API requests are rate-limited to ensure fair usage across all users.

120

Requests per minute

5,000

Requests per hour

100,000

Requests per day

When rate limited, the API returns a 429 status code with a Retry-After header.

X/Twitter Endpoints

POST

/profile

1 credit

Scrape a user profile from X/Twitter. Returns user details including bio, follower count, following count, tweet count, and profile metadata. Cost: 1 credit per request.

Name	Type	Required	Description
`username`	string	required	X/Twitter handle (without @)

Code Samples

curl -X POST https://api.datapio.app/profile \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"username": "elonmusk"}'

POST

/tweets

ceil(count / 20) credits

Scrape recent tweets from a user on X/Twitter. Returns a list of tweets with text, engagement metrics, and media attachments.

Name	Type	Required	Description
`username`	string	required	X/Twitter handle (without @)
`count`	integer	optional	Number of tweets to fetch. Range: 1–100. Default: 20. Cost: ceil(count / 20) credits.
`includeReplies`	boolean	optional	Include reply tweets. Default: false.

Code Samples

curl -X POST https://api.datapio.app/tweets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"username": "elonmusk", "count": 20}'

POST

/mentions

ceil(count / 20) credits

Scrape mentions of a user on X/Twitter. Returns tweets that mention the specified user.

Name	Type	Required	Description
`username`	string	required	X/Twitter handle (without @)
`count`	integer	optional	Number of mentions to fetch. Range: 1–100. Default: 20. Cost: ceil(count / 20) credits.

Code Samples

curl -X POST https://api.datapio.app/mentions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"username": "elonmusk", "count": 20}'

POST

/search

ceil(count / 20) credits

Search for tweets on X/Twitter by keyword or query. Supports advanced search operators.

Name	Type	Required	Description
`query`	string	required	Search query. Supports X advanced search operators.
`count`	integer	optional	Number of results to fetch. Range: 1–1000. Default: 20. Cost: ceil(count / 20) credits.
`searchType`	"latest" \| "top"	optional	Sort order. Default: "latest".

Code Samples

curl -X POST https://api.datapio.app/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"query": "artificial intelligence", "count": 20}'

Error Codes

All errors follow a consistent format with a status code and message.

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}

Code	Status	Description
400	Bad Request	Invalid request body or missing required fields.
401	Unauthorized	Missing or invalid API key in Authorization header.
402	Insufficient Credits	Not enough credits to complete the request.
404	Not Found	The requested resource was not found.
429	Rate Limited	Too many requests. Retry after the indicated time.
500	Internal Error	Something went wrong on our end. Please retry.
503	Service Unavailable	The scraping service is temporarily unavailable.