GET: Rating Change Explanations – Bitsight Knowledge Base

https://api.bitsighttech.com/ratings/v1/insights/rating_changes

See rating change explanations (RCE), as highlighted in the Security Ratings Changes chart. Typically, only negative changes have an associated event.

Parameters

See query parameters for details on the following parameters:

limit (default: ↻ 100)
offset (default: ↻ 0)

company

[Query] Filter by companies.

Value: [String] Comma-separated company unique identifiers [entity_guid]. See GET: Portfolio Details.

date_gte

[Query] Filter up to a specified date.

Value: [String] YYYY-MM-DD

date_lt

[Query] Filter from a starting specified date.

Value: [String] YYYY-MM-DD

score_delta_gte

[Query] Filter by rating change explanations (RCE) so that the delta is higher or equal to the specified value.

Value: [Integer] Rating change points.

score_delta_lt

[Query] Filter by rating change explanations (RCE) so that the delta is lower than the specified value.

Value: [Integer] 0 = Include rating changes of 10 points or less.

↻ Default: Filter by a delta lower than -10 points.

Example Request

curl https://api.bitsighttech.com/ratings/v1/insights/rating_changes -u api_token:

Example Response

{
  "links":{
    "next":"https://api.bitsighttech.com/ratings/v1/insights/rating_changes?limit=100&offset=100",
    "previous":null
  },
  "count":111922,
  "results":[
      […]
      {
        "date":"2022-03-24",
        "start_score":620,
        "end_score":600,
        "reasons":[
          {
            "start_percentile":60.383198,
            "risk_vector":"pot_exploited",
            "end_percentile":54.58032
          }
        ],
        "type":"rating-change",
        "company":"a940bb61-33c4-42c9-9231-c8194c305db3"
    }
  ]
}

Response Attributes

Field					Description
links Object					Navigation for multiple pages of results. See pagination.
	next String				The URL for navigating to the next page of results.
	previous String				The URL for navigating to the previous page of results.
count Integer					The number of rating changes.
results Array					Rating changes and their details.
	Object				A rating change.
		date String [`YYYY-MM-DD`]			The date when the rating changed.
		start_score Integer			The rating before the change.
		end_score Integer			The rating after the change.
		reasons Array			Reasons for the change.
			Object		A reason.
				start_percentile Decimal	The percentile that this organization was placed in, at the beginning of the day. This is based on its rating within the industry.
				risk_vector String	The risk vector slug name or a general change (`explanation`). Values: `botnet` = Botnet Infections `spam` = Spam Propagation `mal_server` = Malware Servers `unexp_comm` = Unsolicited Communications `pot_exploited` = Potentially Exploited `spf` = SPF Domains `dkim` = DKIM Records `certificate` = TLS/SSL Certificates `ssl` = TLS/SSL Configurations `open_port` = Open Ports `http_headers` = Web Application Headers `pc` = Patching Cadence `insecure_sys` = Insecure Systems `server_software` = Server Software `endpoint_pc` = Desktop Software `endpoint_mobile` = Mobile Software `dnssec` = DNSSEC `mobile_appsec` = Mobile Application Security `torrent` = File Sharing `breach` = Security Incidents
				headline String	A summary of the change (if available).
				end_percentile Decimal	The percentile that this organization was placed in at the end of the day. This is based on its rating within the industry.
		type String			For internal Bitsight use.
		company String [`entity_guid`]			This company’s unique identifier.

Response Codes

See some common errors and status codes.

200 – Okay: Everything worked as expected.
400 – Bad Data: This can often be due to missing a required parameter.
401 – No Authentication: No valid API token was provided.
403 – Unauthorized: You do not have permission to access this resource.

June 28, 2022: Published.

Parameters

Example Request

Example Response

Response Attributes

Response Codes

Related articles