ESG
Entities

Entities CES Peaks

Get the driver of each CES peak of an entity.

The CES is only available 48 hours after an entity is registered. Before that, the route returns a Forbidden error.

GET
https://api.textreveal.com/v3/entities/{entity_id}/esg/ces/peak

This route returns the drivers of peak of the CES: for each peak of the CES curve, the event that explains why the CES displays that value at that date.

A peak is a point where the CES rises, usually because a new ESG event was detected or because the media coverage of an existing event grew. The data returned here is the reason behind the value you see on the curve: each peak is justified by one event_id.

How to use it

  1. Retrieve the CES history of the entity with Entities CES and plot it.
  2. Call this route to get the peaks of the same period.
  3. Use the event_id of a peak to retrieve the details of the event (title, categories, documents) with Entities ESG Events.

For example, if the CES jumps on March 12, this route tells you which event caused the jump, so you can display or audit the justification of that value.

Request

Parameters

  • entity_id*uuid

    Permanent ID of the entity

    Example: "753c48d6-23c8-5fb0-9230-b099898452b5"
  • sizeinteger

    Number of records per page

    Default: 10Range: [1, 1000]
  • search_afterstring

    search_after field value from the previous page

  • datedate (operator)

    Extraction date

    Example: "between:2022-01-01;2022-01-02"
  • order(field:direction (enum))[]

    Order to apply to the result.

    Possible fields are: date.

    Possible directions are: asc and desc.

    Default: [date:asc]Example: "date:asc"
  • periodstring (enum)

    Calendar period (all, day, week, month, quarter, year; default all) over which the highest CES peak is returned.

    With all, a single peak is returned: the highest over the whole range filtered by date.

    Example: with period=month, the result contains each month's highest peak and its driver (event_id).

    Default: "all"Values: "all", "day", "week", "month", "quarter", "year"

Response

Response - 200

One peak per period, with its CES score and the event driving it

  • data*object[]

    Paginated list of CES peaks per entity

  • size*integer

    Number of records per page requested.

    Minimum: 1
  • has_next*boolean

    True if there are more records available.

    Example: true
  • count*integer

    Number of records returned in the current page.

    Minimum: 0
  • search_after*string | null

    Cursor for next page.

Response
{
  "data": [
    {
      "period_start_date": "2025-05-06",
      "period_end_date": "2025-05-13",
      "event_id": "e7c2464e-0dc8-441a-970b-0d23eeabe3d1",
      "ces_score": 89
    }
  ],
  "size": 1,
  "has_next": true,
  "count": 1,
  "search_after": "string"
}

Error

Error - 400

Bad request

  • message*string

    Error message.

    Example: "Check the errors field for more details"
  • code*number

    Error code.

    Example: 400
  • reason*string

    Error reason.

    Example: "invalid"
  • errorsobject[]

    Possible error causes.

Response
{
  "message": "Check the errors field for more details",
  "code": 400,
  "reason": "invalid",
  "errors": [
    {
      "message": "string",
      "field": "size",
      "reason": "invalid_type"
    }
  ]
}

Error - 401

Unauthorized

  • message*string

    Error message.

    Example: "Authorization header is expected"
  • code*number

    Error code.

    Example: 401
  • reason*string

    Error reason.

    Example: "unauthorized"
  • errors*object[]
    Array length: [1, 1]
Response
{
  "message": "Authorization header is expected",
  "code": 401,
  "reason": "unauthorized",
  "errors": [
    {
      "message": "Required",
      "field": "headers.authorization",
      "reason": "invalid_type"
    }
  ]
}

Error - 402

Payment required

  • message*string

    Error message.

    Example: "Your account does not have access to this entity. Contact SESAMm sales for more information."
  • code*number

    Error code.

    Example: 402
  • reason*string

    Error reason.

    Example: "forbidden"
Response
{
  "message": "Your account does not have access to this entity. Contact SESAMm sales for more information.",
  "code": 402,
  "reason": "forbidden"
}

Error - 403

Forbidden

  • message*string

    Error message.

    Example: "Missing required permissions to perform this action."
  • code*number

    Error code.

    Example: 403
  • reason*string

    Error reason.

    Example: "forbidden"
Response
{
  "message": "Missing required permissions to perform this action.",
  "code": 403,
  "reason": "forbidden"
}

Error - 404

Not found

  • message*string

    Error message.

    Example: "The requested entity does not exist or is not visible to your company."
  • code*number

    Error code.

    Example: 404
  • reason*string

    Error reason.

    Example: "not_found"
Response
{
  "message": "The requested entity does not exist or is not visible to your company.",
  "code": 404,
  "reason": "not_found"
}

Error - 405

Method not allowed

  • message*string

    Error message.

    Example: "Method Not Allowed"
  • code*number

    Error code.

    Example: 405
  • reason*string

    Error reason.

    Example: "invalid"
Response
{
  "message": "Method Not Allowed",
  "code": 405,
  "reason": "invalid"
}

Generic errors are not shown, see Errors for more details.