Create a new observation

post

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/observations/add

Records a new observation within a project.
Requires a name, and can include a description, reference URL, status, tags, and attachments (images/files).
Observations are the first step in the ideation process, leading to hypotheses.
The Knowledge Base article "Observations Feature Guide" details this: "Observations serve as the starting point in documenting insights."

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

account_id

integer

required

ID of the account that owns the retrieved/saved data

project_id

integer

required

ID of the project into which the observation is to be stored

Query Params

expand

array of objects

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

expand

Allowed:

Body Params

name

string

required

length ≤ 100

A user-defined, concise title for the observation (e.g., "Users drop off on pricing page", "High bounce rate on mobile landing page", "Positive feedback on new feature idea").

description

string | null

(Optional) A detailed description of the observation, including context, data points, user quotes, or any relevant details that support the insight.

status

string

enum

Defaults to active

The current status of an observation in its lifecycle:

active: The observation is current, under consideration, or being actively discussed. This is the default for new observations.
archived: The observation has been reviewed and is no longer actively being pursued (e.g., deemed not actionable, superseded, or already addressed). It's kept for historical records.
Knowledge Base: "Observations Feature Guide" - "Status Management".

Allowed:

url

string | null

(Optional) A URL relevant to this observation, such as the page where the behavior was observed or a link to an analytics report.

images

array of objects | null

This is the document that is used as a visual representation of the observe feature

images

files

array of objects | null

This is the document that is used as a visual representation of the observe feature

files

201Detailed information for a single observation, including its name, description, URL, status, creator, attachments (images/files), and associated tags.

defaultIndicates an error occurred while processing the request. The code provides an HTTP status code, message offers a human-readable explanation or an array of validation errors, and fields (if present) specifies which input fields were problematic.