Security Performance Management
Continuous Monitoring
Cyber Insurance
National Cybersecurity

Articles in this section

See more

GET: Detailed Company Observations

Avatar
Ingrid
Follow
  • March 23, 2021: Filter (grades) by Compromised Systems and User Behavior finding grades.
  • August 18, 2020: Linked to observation details.

⇤ Companies

https://api.bitsighttech.com/ratings/v1/companies/company_guid/observations

Retrieve detailed information (observations) about the risk category data of companies in your portfolio.

The information is similar to what is shown on the Forensics view of a security rating report, but includes Compromised Systems, Diligence, and User Behavior. Observations do not all necessarily impact the company’s rating.

Events and Observations

The Bitsight platform normally displays events in groups so that the relation between individual events is obvious, especially if they span several days. This endpoint shows the individual events that comprise the ones shown in the platform.

Example: An event shown in the platform that spans 8 days may show up as 8 or more separate observations in the API.

Parameters

Observations can be filtered with query parameters to make it easier to pick out relevant items from our data stores.

*Required.

Parameter Description Values 
company_guid
Path		 The company to query. [String] Company unique identifier [entity_guid]. See GET: Portfolio Details. 
domain_name
Query		 Filter by domain name.

Not all observations are associated with a domain.

 [String] Domain name.
Example: www.example.com
 
end_date
Query		 Filter by the observation’s end date. [String] YYYY-MM-DD 
grades
Query		 Filter by finding grade. [String] Comma-separated finding grades. 
ip_address
Query		 Filter by IP address.

Not all observations are associated with an IP address.

 [String] Any IPv4 address in dotted notation or an IPv6 address.
Examples:
  • IPv4 address = 192.0.2.0
  • IPv6 address = 2001:DB8::
 
limit
Query		 Set the maximum number of results. The results will include fewer records (even zero), but not more. [Integer] Any number from 1 to 1000.
Default: 100
 
port
Query		 Filter observations on a particular network port. [Integer] The port number, up to 65535. 
risk_types
Query		 Filter by observation risk type. Access to some risk types is dependent on the subscription type. [String] Comma-separated risk types. 
start_date
Query		 Filter by the observation’s starting date. [String] YYYY-MM-DD

Example Request

Use a company’s unique identifier (GUID) to look up its observations. You may opt to specify one or more risk types to return. See the query parameters or refer to the pagination recommendations.

curl 'https://api.bitsighttech.com/ratings/v1/companies/company_guid/observations?risk_types=risk_type' -u api_token:

Example Response

If you specified more than one risk type in the risk_types parameter of your request, the server will respond with an array of individual records from all the risk types you requested.

{
  {
    "data":[
      {
        "risk_type":"botnet_infections",
        "observation_id":"AAAAA1CH3qvE2t7jAAAAAHBXFvY=",
        "collection_date":"2020-08-05",
        "event_date":"2020-08-05",
        "forensics":{
 
          ⊕ See Event Forensic Details
 
        },
        "details":{
 
          ⊕ See Observation Details
 
        }
      }
    ],
    "cursors":{
      "next":"AAAAAAAAAGQKl0_OUZg4Yw==",
      "next_url":"https://api.bitsighttech.com/ratings/v1/companies/a940bb61-33c4-42c9-9231-c8194c305db3/observations?cursor=AAAAAAAAAGQKl0_OUZg4Yw%3D%3D"
    }
  }
}

Response Attributes

Observations are sorted by date, with the most recent first.

If the system returns a “Detail not found” message, please try using query parameters. No results matched the specified query parameters. Double check to make sure the specified parameters are spelled correctly or see the full list of parameters.

Observations will be returned as JSON and cannot be returned as XML. A JSON object is returned by the API with a data array field. Separate objects of individual observations are within the data array, with the following attributes:

Field Description 
data
Array		 Observations for the queried company.
  
risk_type
String		 The slug name of this observation’s risk type. 
observation_id
String		 The unique identifier of this observation. 
collection_date
String [YYYY‑MM‑DD]		 The date when the observation was collected from the data source. 
event_date
String [YYYY‑MM‑DD]		 The date when this observation was considered as an event. 
forensics
Object		 Fields for conducting network forensics.
  
domain_name
String		 The host domain. 
host_ip
String		 The host IP address. 
host_port
Integer		 The host port number. 
details
Object		 Observation details.
  The included details vary depending on the risk vector. See observation details by risk type. 
occurrences
Object		 Occurrence details.
  
first_seen
String [YYYY‑MM‑DD HH:MM:SS]		 The starting date and time of this occurrence’s duration. 
last_seen
String [YYYY‑MM‑DD HH:MM:SS]		 The ending date and time of this occurrence’s duration. 
representative_timestamp
String [YYYY‑MM‑DD HH:MM:SS]		 The representative date and time of this occurrence. 
count
Integer		 The number of times this observation was counted. 
cursors
Object		 An opaque base64-encoded string that allows you to get the next or previous page of results, which is included with select endpoints with large datasets. If a query matches very few observations and the response contains a cursor but no data, the cursor can then be used to ask the server to continue searching.
  
next
String		 The unique identifier of the next observation. 
next_url
String		 The URL to navigate to the next page of results.

Related articles