| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Retrieves ESG classified news articles for a company, as a paginated list.
When to use it
To monitor a company for ESG developments. Call the endpoint on a schedule with published_after set to the date of your previous run, so each response carries only articles you have not already seen.
To screen for adverse media. Filter to sentiment=Negative to retrieve only coverage of controversies, environmental damage, labour issues, and governance failures.
To review coverage on a specific ESG topic. Filter by pillar or theme to narrow a company's coverage to the dimension your assessment is concerned with.
Filtering the result set
Four optional filters narrow the articles returned. pillar, theme, and sentiment accept exact values only, with no fuzzy matching.
| Parameter | Accepted values |
|---|---|
published_after | A date, YYYY-MM-DD. Returns articles published on or after it. Must not be a future date. |
pillar | Environmental, Social, Governance. |
theme | A theme from the ESG taxonomy, such as Climate Change or Human Rights. |
sentiment | Positive, Negative, Neutral. |
See ESG risk taxonomy for the full set of pillar and theme values.
Filters narrow the response, and nothing moreThese parameters filter the result set on the API side. They do not change which articles are gathered for the company, and they do not influence whether newer coverage is gathered. That is decided separately, based on how recently the company was last processed.
In particular, a narrow
published_afterdoes not reduce the work behind the request, and a broad one does not cause more to be gathered.
Results pagination
Results are paginated using the same cursor based mechanism as other Veridion APIs. See the Pagination section for the parameters and tokens.
Capping how many articles you receive
max_resultscaps the total number of articles returned across a pagination session. Because articles are ranked, capping keeps the most relevant coverage rather than cutting the result set off arbitrarily.result_countreports the total number of articles matching your filters and ignores themax_resultscap.
Sendmax_resultson every requestThe cap is not carried in the cursor. If you omit it when requesting a later page, it stops applying and paging continues through the full result set.
Successful response
Every response carries the same envelope, whatever state the request is in.
| Field | What it holds |
|---|---|
veridion_id | The company you requested. |
status | The state of the request. See Response states below. |
active_processing_session | The session currently gathering data for this company, or null where none is running. See Following a processing session below. |
last_computed_at | When the most recent completed processing for this company finished. Independent of your filters and paging: it describes when the data was produced, not which slice you are viewing. null only where no processing has ever completed for this company. |
result_count | Total articles matching your filters across the whole result set, not only this page. |
result | The articles on this page. An empty array where nothing has been gathered for the company. |
next_cursor | Cursor for the next page, or null on the last page. |
has_more | Whether more articles match beyond this page. |
Response fieldsFor a comprehensive list of all data points returned on an ESG news article, see the Response fields and types page.
Response states
status takes one of three values.
status | Meaning | What to do |
|---|---|---|
complete | The articles held for this company are current. A complete response can also carry an empty result, meaning no articles are available for this company at present. | Consume what is returned. An empty result is a valid answer rather than an error. |
processing | Newer coverage is being gathered in the background. Any articles already held are returned alongside, so this does not imply an empty response. | Request again after a short interval, or watch the processing session for the count to rise. |
not_found | The company was not found in Veridion's data sources. | Check the veridion_id. Repeating the request immediately returns the same answer. |
Branch onstatus, not on the HTTP codeEvery outcome of this endpoint is
200 OK, includingnot_found. Thestatusfield in the body is the answer.
An empty result is not a dead endA
completeresponse with an emptyresultmeans no articles are available for this company at present. Requesting again later may return articles, so you can re-check on your own schedule rather than treating the empty response as final.
Following a processing session
While status is processing, the response carries an active_processing_session, identifying the session gathering data for this company. It is null in every other state, because no session is running. Read more about processing sessions.
Capture it from a processing response if you intend to poll. Pass it to Get processing status to check on that session, and to see how many articles are available at request time, without requesting a page of articles again. That endpoint is read-only.
Poll the session rather than re-requesting a pageWhere you are waiting on articles to arrive, the session endpoint is the easier way to watch progress: it reports the state of the session and an article count, without transferring the articles themselves. Request a page from this endpoint once the count tells you there is something worth fetching.
That count covers every article held for the company, not only those produced by the session you are polling, and it takes no filters. Expect it to start at whatever was already held and climb from there.
A rising count is progressArticles are counted as they arrive, so the number climbs while a session runs rather than jumping once at the end. There is no guaranteed rate, and a count that has not moved for a moment does not mean the session has finished.
Use
statusto determine completion, and the count only to judge whether there is enough to work with and decide to start fetching the results.
Example: articles returned
{
"veridion_id": "abc-123",
"status": "complete",
"active_processing_session": null,
"last_computed_at": "2026-02-15T10:30:00.000Z",
"result_count": 42,
"result": [
{
"source_url": "https://example.com/article",
"headline": "Company announces emissions reduction target",
"content_summary": "A generated summary of the article ...",
"esg_pillar": "Environmental",
"esg_theme": "Climate Change",
"esg_risk_criteria": "Carbon Footprint",
"esg_sentiment_value": "Positive",
"esg_sentiment_confidence": 0.95,
"published_date": "2026-02-15"
}
],
"next_cursor": "eyJyIjpbIjE3MjFhM...",
"has_more": true
}Example: nothing held yet, data being gathered
{
"veridion_id": "abc-123",
"status": "processing",
"active_processing_session": "0c5b4e7a-1d52-4a4f-9c3c-1e0e5e8f1a2b",
"last_computed_at": null,
"result_count": 0,
"result": [],
"next_cursor": null,
"has_more": false
}Error responses
400 Bad Request, wherepublished_afteris a future date, orcursoris malformed or no longer matches the current result set.- other standard HTTP error responses, detailed in the Response codes section.
Any error response follows a specific structure. Please see the Error response format section for more details.