Skip to content

Beta
List observations

Request

Lists observations with paging, filters, and open/resolved mode. View is server-determined from the caller's domain entitlement.

Bodyapplication/jsonrequired

Pagination, filters, and open/resolved mode for listing observations on the public API. View (VRM vs self) is determined server-side from the caller's entitlement and is not a request input.

sortFieldstring

Field name to sort results by.

sortOrderstring(SortOrder)

Sort direction for list and search APIs: ascending, descending, or unspecified.

Default:"SORT_ORDER_UNSPECIFIED"
Enum:"SORT_ORDER_UNSPECIFIED""SORT_ORDER_ASC""SORT_ORDER_DESC"
limitinteger, (int32)

Maximum number of observations to return per page.

offsetinteger, (int32)

Zero-based offset for page-based pagination; ignored when cursor is provided.

filtersArray of objects(PublicFilter)required

Filter expressions applied to narrow the result set.

includeFilterOptionsboolean

When true, the response includes available filter option values for the current result set.

queryModestring(ObservationsQueryMode)required

Whether list endpoints return open items, resolved items, or an unspecified default.

Default:"OBSERVATIONS_QUERY_MODE_UNSPECIFIED"
Enum:"OBSERVATIONS_QUERY_MODE_UNSPECIFIED""OBSERVATIONS_QUERY_MODE_OPEN""OBSERVATIONS_QUERY_MODE_RESOLVED"
cursorstring

Opaque cursor for keyset pagination. Set to "" to request the first page; omit (leave unset) to use offset-based pagination instead.

observationGroupOrnstring(ORN identifying an observation group (format: `orn:<version>:observation:group:<key>:<view-owner-domain>`). When provided, the server narrows results to observations in that group by appending an internal filter on the observation name key derived from the ORN)
POST
/public/v1/observations
curl -i -X POST \
  https://docs.titanapi.securityscorecard.io/_mock/openapi.public/public/v1/observations \
  -H 'Content-Type: application/json' \
  -d '{
    "sortField": "string",
    "sortOrder": "SORT_ORDER_UNSPECIFIED",
    "limit": 0,
    "offset": 0,
    "filters": [
      {
        "list": {
          "operator": "OPERATOR_UNSPECIFIED",
          "isNegated": true,
          "filters": [
            {}
          ]
        },
        "rule": {
          "field": {
            "observationsField": "OBSERVATIONS_FIELD_UNSPECIFIED"
          },
          "comparison": "COMPARISON_UNSPECIFIED",
          "value": {
            "stringValue": "string",
            "numberValue": 0.1,
            "boolValue": true,
            "stringListValue": {
              "values": [
                "string"
              ]
            },
            "numberRangeValue": {
              "min": 0.1,
              "max": 0.1
            },
            "dateRangeValue": {
              "startTime": "2019-08-24T14:15:22Z",
              "endTime": "2019-08-24T14:15:22Z",
              "live": true
            },
            "dateValue": "2019-08-24T14:15:22Z"
          }
        }
      }
    ],
    "includeFilterOptions": true,
    "queryMode": "OBSERVATIONS_QUERY_MODE_UNSPECIFIED",
    "cursor": "string",
    "observationGroupOrn": "string"
  }'

Responses

A successful response.

Bodyapplication/json
observationsArray of objects(/ Observation class / Represents an individual observation on a single asset / Designed to unify DNS hostname, URL, (IP, port, proto) tuple / Also contains the evidence because evidence is always tied to an observation)required

The observations matching the request filters and group.

totalCountinteger, (int32)required

Total number of observations matching the query (before pagination).

filterOptionsArray of objects(PublicFilterOption)required

Filter option values available for the current result set; populated when include_filter_options is true.

nextCursorstring

Opaque cursor to pass as cursor in the next request. Absent when no further pages exist.

Response
{
  "observations": [
    { … }
  ],
  "totalCount": 0,
  "filterOptions": [
    { … }
  ],
  "nextCursor": "string"
}