Datasets API endpoint
Returns distribution counts over the journalists index (dataset id enum value `journalists`), honoring the same filters as search. Facet enum: `outlet`, `vertical`, `topic`, `contact_type`, `record_type`, `role_type`, `email_kind`, `outreach_readiness_band`. `facet=outlet` returns every outlet (up to 1000) in one response; other facets return their top 50 values. Facets are not paginated: `page` and `page_size` are ignored.
/datasets/journalists/facetsDataset id enum:
journalistsQuery parameters:
facet: required facet to aggregate. Allowed values: outlet, vertical, topic, contact_type, record_type, role_type, email_kind, outreach_readiness_band.q: optional full-text match on the journalist's name, title, and bio, max 256 characters.outlet: optional exact outlet id filter.vertical: optional exact beat-vertical filter. Allowed values: tech, crypto, marketing, consumer_tech, consumer_policy, cybersecurity, health, gaming, climate, business, entertainment, sports, legal, science, politics, real_estate, automotive, travel, food, education, design, film_tv, fashion, music, personal_finance, tech_independent, culture_independent, local_news, construction, banking, retail, aerospace_defense, energy, agriculture, local_business, general_news.topic: optional exact topic filter.contact_type: optional contact-availability filter. Allowed values: email, social, none.record_type: optional record-shape filter. Allowed values: person, desk, organization, syndicated_byline, unknown.role_type: optional role filter. Allowed values: staff, editor, reporter, contributor, freelancer, columnist, non_editorial, unknown.email_kind: optional email classification filter. Allowed values: individual_work, individual_personal_public, shared_desk, tips_or_submissions, outlet_generic, unknown.outreach_readiness_band: optional outreach-readiness filter. Allowed values: ready, promising, limited, no_contact.min_outreach_readiness: optional minimum score from 0 to 100; the facet then describes only records meeting that threshold.Response behavior:
facet=outlet returns every outlet id (up to 1000; the registry holds roughly 230) to use as the outlet search/item filter, with counts, in a single response. Other facets return their top 50 values.page and page_size are accepted for parity with search but ignored, so page=2 returns the same buckets as page=1.facet=contact_type shows whether a record has an email, social handle, or neither. facet=email_kind, facet=record_type, and facet=role_type expose the quality dimensions used to build safer outreach lists.facet=outreach_readiness_band groups records into ready, promising, limited, and no_contact prioritization bands.items array (not an error) when the dataset has no data yet.| Field | Filled in, of 232 checked | Values in the sample |
|---|---|---|
| value | 232 | |
| count | 232 | 1 to 6,506, median 44 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| facet | string | Yes | Facet enum: outlet, vertical, topic, contact_type, record_type, role_type, email_kind, outreach_readiness_band Allowed values: outlet, vertical, topic, contact_type, record_type, role_type, email_kind, outreach_readiness_band. | outlet | |
| q | string | No | Full-text match on the journalist's name, title, and bio, max 256 characters | ||
| outlet | string | No | Exact outlet id filter | ||
| vertical | string | No | Exact beat-vertical filter. Enum: tech, crypto, marketing, consumer_tech, consumer_policy, cybersecurity, health, gaming, climate, business, entertainment, sports, legal, science, politics, real_estate, automotive, travel, food, education, design, film_tv, fashion, music, personal_finance, tech_independent, culture_independent, local_news, construction, banking, retail, aerospace_defense, energy, agriculture, local_business, general_news Allowed values: tech, crypto, marketing, consumer_tech, consumer_policy, cybersecurity, health, gaming, climate, business, entertainment, sports, legal, science, politics, real_estate, automotive, travel, food, education, design, film_tv, fashion, music, personal_finance, tech_independent, culture_independent, local_news, construction, banking, retail, aerospace_defense, energy, agriculture, local_business, general_news. | ||
| topic | string | No | Exact topic filter | ||
| contact_type | string | No | Contact-availability filter. Enum: email, social, none Allowed values: email, social, none. | ||
| record_type | string | No | Record classification filter. Enum: person, desk, organization, syndicated_byline, unknown Allowed values: person, desk, organization, syndicated_byline, unknown. | ||
| role_type | string | No | Role classification filter. Enum: staff, editor, reporter, contributor, freelancer, columnist, non_editorial, unknown Allowed values: staff, editor, reporter, contributor, freelancer, columnist, non_editorial, unknown. | ||
| email_kind | string | No | Email semantics filter. Enum: individual_work, individual_personal_public, shared_desk, tips_or_submissions, outlet_generic, unknown Allowed values: individual_work, individual_personal_public, shared_desk, tips_or_submissions, outlet_generic, unknown. | ||
| min_outreach_readiness | integer | No | Minimum outreach-readiness score, from 0 to 100 | ||
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/journalists/facets?facet=outlet&q=coffee&vertical=tech&contact_type=email&record_type=person&role_type=staff&email_kind=individual_work" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "journalists",
"facet": "contact_type",
"items": [
{
"value": "email",
"count": 42
},
{
"value": "social",
"count": 61
},
{
"value": "none",
"count": 8
}
]
}
}Request schema
No body schema
Response schema
#/definitions/datasets.journalistsFacetResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.JournalistsFacetResponse | No | ||||
| data.dataset | string | No | ||||
| data.facet | string | No | ||||
| data.items | array | No | ||||
| data.items[].count | integer | No | ||||
| data.items[].value | string | No | ||||
| 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/journalists/facets?facet=outlet&q=coffee&vertical=tech&contact_type=email&record_type=person&role_type=staff&email_kind=individual_work" \
-H "x-api-key: $CRAWLORA_API_KEY"