> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forestreet.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get an Observation
>
Retrieves a single observation based on the provided observation ID.
**Subscription Endpoint**
This endpoint has a special subscription requirement. Your API Key needs to be
subscribed to this endpoint in order to access it; otherwise it will return a 403
Forbidden error. Please contact Forestreet support to get subscribed.
An Observation is a piece of information or data point that has been collected and
stored in our system. It serves as the foundational unit of information to join
together as Events, and can represent various types of data such as news articles,
social media posts, analyst reports, or any other relevant information that we want to
track and analyze. Each observation contains metadata about its source, content,
publication time, and other relevant attributes that allow us to process and analyze
it effectively.
## OpenAPI
````yaml get /v2/events-monitor/observation/{observationId}
openapi: 3.0.0
info:
title: Forestreet API
version: 1.0.0
description: API documentation for Forestreet API
servers:
- url: https://rest.forestreet.com
description: Forestreet API V2 server
security:
- apiKeyAuth: []
- bearerAuth: []
- sessionIdQuery: []
tags: []
paths:
/v2/events-monitor/observation/{observationId}:
get:
tags:
- Events Monitor
summary: Get an Observation
description: |2-
Retrieves a single observation based on the provided observation ID.
**Subscription Endpoint**
This endpoint has a special subscription requirement. Your API Key needs to be
subscribed to this endpoint in order to access it; otherwise it will return a 403
Forbidden error. Please contact Forestreet support to get subscribed.
An Observation is a piece of information or data point that has been collected and
stored in our system. It serves as the foundational unit of information to join
together as Events, and can represent various types of data such as news articles,
social media posts, analyst reports, or any other relevant information that we want to
track and analyze. Each observation contains metadata about its source, content,
publication time, and other relevant attributes that allow us to process and analyze
it effectively.
parameters:
- schema:
type: string
description: The unique identifier of the observation
example: 69e89d74df2753cf786ef002
required: true
description: The unique identifier of the observation
name: observationId
in: path
responses:
'200':
description: >-
The response containing pagination metadata, and an array of zero or
more events that satisfy the query parameters.
content:
application/json:
schema:
type: object
properties:
_id:
type: string
description: Unique identifier for the observation
example: 69e89d74df2753cf786ef002
dedupeId:
type: string
description: >-
A deduplication identifier for the observation, used to
identify and merge duplicate observations.
example: >-
NewsArticle::url(https://www.dw.com/en/czechias-lithium-mine-plans-spark-resistance/video-76878114)
sourceService:
type: string
description: >-
The service from which the observation was sourced, e.g.
'News Monitor'.
example: News Monitor
title:
type: string
description: >-
Title of the observation. For news articles, this will
typically be the native title of the article from the
publisher.
example: Czechia's lithium mine plans spark resistance
content:
type: array
items:
type: string
description: >-
An array of text snippets that provide the content of the
observation. For news articles, this may include the
article summary, key sentences, or other relevant text
extracted from the article. If an article failed to
scrape, it may only contain 1 content item which is the
search engine snippet.
The content items may have been pruned before being stored
on our system, so that only the most relevant information
is retained. It is not guaranteed to be the full text of
the original source.
example:
- >-
Plans to mine lithium in Cinovec, a mountain town on the
Czech-German border, are dividing local communities.
While the project promises jobs and investment...
- >-
Plans to mine lithium in Cinovec, a mountain town on the
Czech-German border, are dividing local communities.
While the project promises jobs and investment,
residents fear it could bring pollution and harm
tourism.
- Czechia's lithium mine plans spark resistance
- >-
In Cinovec, a small mountain town on the Czech- German
border, plans to mine lithium have divided locals.
- >-
Known for its clean air, forests and spa tourism, the
region around Cinovec has reportedly got one of Europe's
largest lithium deposits, a resource seen as vital to
the green energy transition.
- >-
According to Geomet, the company behind the project,
mining will bring jobs and economic growth. But many
residents fear it could harm the region's fragile
ecosystem, which is still recovering from decades of
coal mining.
- >-
As miners scour Zambia for metals used in sustainable
energy, locals are dealing with unchecked pollution.
textEmbedding:
type: array
items:
type: number
description: >-
An array of numbers representing the embedding vector for
the observation's content.
example:
- 0.123
- -0.456
- 0.789
weight:
type: object
additionalProperties:
type: number
description: >-
A dictionary of weights for the observation, where the
keys are weight names (e.g. 'Media Bias Multiplier') and
the values are the corresponding weight values. These
weights can be used to adjust the importance of the
observation in various algorithms, such as event
clustering or impact assessment.
example:
Media Bias Multiplier: 1.992
publishedAt:
type: string
nullable: true
description: >-
The date and time when the observation was published or
recorded. These are always UTC.
example: '2026-04-21T17:02:22.885Z'
addedAt:
type: string
nullable: true
description: >-
The date and time when the observation was added to our
system. These are always UTC.
example: '2026-04-22T10:02:22.885Z'
clusterLabel:
type: object
properties:
label:
type: number
description: >-
The cluster label, represented as an integer.
Observations with the same cluster label are
considered to belong to the same event cluster.
example: 3
method:
type: string
description: >-
The method used to determine the cluster label. For
internal use only, the exact value of this field can
change without notice.
example: Leiden
required:
- label
- method
description: >-
The cluster label assigned to this observation, if it has
been clustered.
url:
type: string
format: uri
description: >-
URL of the observation, if it was sourced and scraped from
the internet. Only available on publicly sourced
observations such as News Articles.
example: >-
https://www.dw.com/en/czechias-lithium-mine-plans-spark-resistance/video-76878114
required:
- _id
- dedupeId
- sourceService
- title
- content
- textEmbedding
- weight
- publishedAt
- addedAt
description: The response schema for the Get Observation endpoint.
'400':
description: Invalid query parameters
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
QUERY_VALIDATION_FAILED:
value:
success: false
errorCode: QUERY_VALIDATION_FAILED
message: Invalid query parameters
'401':
description: Unauthorized access - API Key is missing or invalid
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
UNAUTHORISED:
value:
success: false
errorCode: UNAUTHORISED
message: Unauthorized access - API Key is missing or invalid
'403':
description: API Key not subscribed to this endpoint
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
FORBIDDEN:
value:
success: false
errorCode: FORBIDDEN
message: API Key not subscribed to this endpoint
'404':
description: Observation with the given ID not found
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
NOT_FOUND:
value:
success: false
errorCode: NOT_FOUND
message: Observation with the given ID not found
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
INTERNAL_SERVER_ERROR:
value:
success: false
errorCode: INTERNAL_SERVER_ERROR
message: Internal Server Error
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Pass a static API key for every request, provided by your customer
support.
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer token authentication, using a sessionId generated by `GET
/v2/auth/session`.
sessionIdQuery:
type: apiKey
in: query
name: sessionId
description: >-
Session ID passed as a query parameter for authentication, provided by
`GET /v2/auth/session`.
````