curl --request GET \
--url https://api.cloud.corbado.io/v1/observe/annotations \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.cloud.corbado.io/v1/observe/annotations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.cloud.corbado.io/v1/observe/annotations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloud.corbado.io/v1/observe/annotations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.cloud.corbado.io/v1/observe/annotations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.cloud.corbado.io/v1/observe/annotations")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloud.corbado.io/v1/observe/annotations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body[
{
"id": "<string>",
"kind": "event",
"platform": true,
"headline": "<string>",
"approximate": true,
"display": true,
"source": "manual",
"createdMs": 123,
"updatedMs": 123,
"description": "<string>",
"dateFrom": "<string>",
"dateTo": "<string>",
"datePrecision": "month",
"dateFromMs": 123,
"dateToMs": 123,
"status": "open",
"effect": "context",
"reading": "<string>",
"scope": {
"applicationID": "<string>",
"os": "<string>",
"osVersion": "<string>",
"browser": "<string>",
"customTag1": "<string>",
"customTag2": "<string>",
"customTag3": "<string>",
"customTag4": "<string>",
"customTag5": "<string>",
"customTag6": "<string>",
"customTag7": "<string>",
"customTag8": "<string>",
"customTag9": "<string>",
"customTag10": "<string>",
"customTag11": "<string>",
"customTag12": "<string>",
"customTag13": "<string>",
"customTag14": "<string>",
"customTag15": "<string>",
"customTag16": "<string>",
"customTag17": "<string>",
"customTag18": "<string>",
"customTag19": "<string>",
"customTag20": "<string>",
"experimentRunID": "<string>",
"experimentVariantID": "<string>"
},
"series": [
"<string>"
],
"evidence": [
"code"
],
"refs": [
{
"type": "finding",
"value": "<string>"
}
],
"externalKey": "<string>"
}
]{
"error": {
"message": "Validation failed",
"details": [
{
"field": "projectID",
"message": "required"
}
]
}
}List annotations
Lists the project’s annotations together with platform annotations, which apply to every project.
Paginated; sorted by createdMs (default descending).
Filter by kind (repeat the parameter for several kinds); without it all kinds are returned.
fromDate and toDate select a window in project time. A period is returned when it overlaps the
window, an event when its date lies inside it. Annotations without a date and follow-ups (whose date says
when they become ready) are always returned.
Required API key permission: observe:annotations:read.
curl --request GET \
--url https://api.cloud.corbado.io/v1/observe/annotations \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.cloud.corbado.io/v1/observe/annotations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.cloud.corbado.io/v1/observe/annotations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloud.corbado.io/v1/observe/annotations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.cloud.corbado.io/v1/observe/annotations"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.cloud.corbado.io/v1/observe/annotations")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloud.corbado.io/v1/observe/annotations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body[
{
"id": "<string>",
"kind": "event",
"platform": true,
"headline": "<string>",
"approximate": true,
"display": true,
"source": "manual",
"createdMs": 123,
"updatedMs": 123,
"description": "<string>",
"dateFrom": "<string>",
"dateTo": "<string>",
"datePrecision": "month",
"dateFromMs": 123,
"dateToMs": 123,
"status": "open",
"effect": "context",
"reading": "<string>",
"scope": {
"applicationID": "<string>",
"os": "<string>",
"osVersion": "<string>",
"browser": "<string>",
"customTag1": "<string>",
"customTag2": "<string>",
"customTag3": "<string>",
"customTag4": "<string>",
"customTag5": "<string>",
"customTag6": "<string>",
"customTag7": "<string>",
"customTag8": "<string>",
"customTag9": "<string>",
"customTag10": "<string>",
"customTag11": "<string>",
"customTag12": "<string>",
"customTag13": "<string>",
"customTag14": "<string>",
"customTag15": "<string>",
"customTag16": "<string>",
"customTag17": "<string>",
"customTag18": "<string>",
"customTag19": "<string>",
"customTag20": "<string>",
"experimentRunID": "<string>",
"experimentVariantID": "<string>"
},
"series": [
"<string>"
],
"evidence": [
"code"
],
"refs": [
{
"type": "finding",
"value": "<string>"
}
],
"externalKey": "<string>"
}
]{
"error": {
"message": "Validation failed",
"details": [
{
"field": "projectID",
"message": "required"
}
]
}
}Authorizations
Use an Observe API key from the management console. The key selects the project and must grant the permission listed on the operation. Keep this key on your server.
Query Parameters
Kinds to return. Without it, all kinds are returned.
6What the annotation records: event something changed, period something held over a span, setup a fact
about how the project works, interpretation how to read the data, constraint which data may be used,
follow-up an unknown or open work.
event, period, setup, interpretation, constraint, follow-up Window start (inclusive) as a local datetime in project time, formatted as YYYY-MM-DDTHH:MM:SS.
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$"2026-09-01T00:00:00"
Window end (exclusive) as a local datetime in project time, formatted as YYYY-MM-DDTHH:MM:SS.
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$"2026-10-01T00:00:00"
Field to order by; date orders by the start date.
created, date Order direction
asc, desc The page number to retrieve for paginated results.
1
The number of items to return per page. Useful for pagination.
20
Response
Paginated list of annotations. Paging metadata is returned in X-Corbado-Page, X-Corbado-TotalPages, and X-Corbado-TotalItems response headers.
1000Annotation ID (format ann-<number>).
What the annotation records: event something changed, period something held over a span, setup a fact
about how the project works, interpretation how to read the data, constraint which data may be used,
follow-up an unknown or open work.
event, period, setup, interpretation, constraint, follow-up Platform annotation that applies to every project; managed by Corbado.
One line saying what the annotation records.
The date is not exact.
Shown on charts.
Who wrote the annotation or made a change.
manual, agent, system Creation time in milliseconds since epoch.
Last update time in milliseconds since epoch.
Optional Markdown body with details.
Date as stated, in project time (UTC for platform annotations), in the format of its precision.
Last unit a period covers (inclusive), in the same format. Absent on an ongoing period.
Unit the annotation's dates were stated in.
month, date, hour, datetime Start of dateFrom in milliseconds since epoch.
End of the span (exclusive) in milliseconds since epoch.
Where a follow-up stands.
open, done How an event or period changes the reading of the data: context background only, boundary compare only
within one side, degraded data partly wrong, broken data wrong, missing no data.
context, boundary, degraded, broken, missing Reading rule this date brings (events and periods).
Narrows what the annotation applies to, by time-series dimension. Absent means the whole project.
Show child attributes
Show child attributes
504Kind of evidence an annotation rests on.
code, trace, data, customer 50Show child attributes
Show child attributes
Was this page helpful?