Datasets API endpoint
Returns value counts for the X users dataset by the required `facet`: `is_blue_verified`, `has_bio`, `has_external_url` or `source_tier`. The counts follow the search filters, including `q`, follower and ratio ranges, and creation or crawl dates. At most 50 values come back, largest count first.
/datasets/x-users/facetsReturns terms aggregation counts over the X users dataset, honoring the same filters as search.
Dataset id enum:
x-usersQuery parameters:
facet: required facet to aggregate. Allowed values: is_blue_verified, has_bio, has_external_url, source_tier.q: optional full-text query over username, name, bio and location, max 256 characters.username: optional exact username filter (case-insensitive), max 128 characters.source_tier: optional exact filter for which seed tier discovered this account.is_blue_verified: optional filter for the X blue-check verification flag.has_bio: optional filter for a non-empty profile bio.has_external_url: optional filter for a linked external URL.min_followers: optional minimum follower count.max_followers: optional maximum follower count.min_ratio: optional minimum follower-to-following ratio, 0 or greater.max_ratio: optional maximum follower-to-following ratio, 0 or greater.created_after: optional filter for accounts created on or after this date (RFC3339 or YYYY-MM-DD).created_before: optional filter for accounts created on or before this date (RFC3339 or YYYY-MM-DD).crawled_after: optional filter for records last refreshed on or after this date (RFC3339 or YYYY-MM-DD).crawled_before: optional filter for records last refreshed on or before this date (RFC3339 or YYYY-MM-DD).sort: optional sort enum: relevance, followers_desc, followers_asc, crawled_at_desc, crawled_at_asc, created_at_desc, created_at_asc.Response behavior:
50 buckets ordered by descending count.facet is required; unsupported values return the standard invalid params envelope.is_blue_verified, has_bio, has_external_url) return true/false bucket values.source_tier bucket values are the seed tier names, e.g. github-users, wikidata, tiktok-creators, journalists. unknown labels records whose discovery tier was not recorded.items array (not an error) when the dataset has no data yet.| Field | Filled in, of 16 checked | Values in the sample |
|---|---|---|
| value | 16 | |
| count | 16 | 2 to 375,418, median 3,470 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| facet | string | Yes | Facet enum: is_blue_verified, has_bio, has_external_url, source_tier Allowed values: is_blue_verified, has_bio, has_external_url, source_tier. | is_blue_verified | |
| q | string | No | Full-text query over username, name, bio and location, max 256 characters | ||
| username | string | No | Exact username filter (case-insensitive), max 128 characters | ||
| source_tier | string | No | Exact filter for which seed tier discovered this account | ||
| is_blue_verified | boolean | No | Filter by the X blue-check verification flag | ||
| has_bio | boolean | No | Filter by a non-empty profile bio | ||
| has_external_url | boolean | No | Filter by a linked external URL | ||
| min_followers | integer | No | Minimum follower count | ||
| max_followers | integer | No | Maximum follower count | ||
| min_ratio | number | No | Minimum follower-to-following ratio | ||
| max_ratio | number | No | Maximum follower-to-following ratio | ||
| created_after | string | No | Accounts created on or after this date (RFC3339 or YYYY-MM-DD) | ||
| created_before | string | No | Accounts created on or before this date (RFC3339 or YYYY-MM-DD) | ||
| crawled_after | string | No | Records last refreshed on or after this date (RFC3339 or YYYY-MM-DD) | ||
| crawled_before | string | No | Records last refreshed on or before this date (RFC3339 or YYYY-MM-DD) | ||
| sort | string | No | Sort enum: relevance, followers_desc, followers_asc, crawled_at_desc, crawled_at_asc, created_at_desc, created_at_asc Allowed values: relevance, followers_desc, followers_asc, crawled_at_desc, crawled_at_asc, created_at_desc, created_at_asc. | ||
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/x-users/facets?facet=is_blue_verified&q=coffee&is_blue_verified=true&has_bio=true&has_external_url=true&sort=relevance" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "x-users",
"facet": "source_tier",
"items": [
{
"value": "wikidata",
"count": 427709
},
{
"value": "github-users",
"count": 54790
},
{
"value": "tiktok-creators",
"count": 4466
},
{
"value": "journalists",
"count": 840
}
]
}
}Request schema
No body schema
Response schema
#/definitions/datasets.xUsersFacetResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.XUserFacetResponse | No | ||||
| data.dataset | string | No | Identifier of the dataset queried (`x-users`). | |||
| data.facet | string | No | Facet that was aggregated. | |||
| data.items | array | No | Facet values with the number of matching records for each. | |||
| data.items[].count | integer | No | Number of X users in this bucket. | |||
| data.items[].value | string | No | Bucket value for the requested facet, such as `true` or `false` for yes/no facets. | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/datasets/x-users/facets?facet=is_blue_verified&q=coffee&is_blue_verified=true&has_bio=true&has_external_url=true&sort=relevance" \
-H "x-api-key: $CRAWLORA_API_KEY"