Search events

Request description

Endpoint: /events/search
Method: POST

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <accessToken>"
}

Note: the <accessToken> is obtained as a result of the authentication

Payload

interface ISearchEventPayload {
  userId: string;
  startTimestamp: number;
  endTimestamp: number;
  outputFormat?: "json" | "csv";
  limit?: number;
}

where:

  • userId: user identification. Get it from Users list
  • limit: Maximum number of events to return. Integer between 1 and 100, sent as a number (not as a string)
  • startTimestamp: Start time (Unix time in milliseconds)
  • endTimestamp: End time (Unix time in milliseconds). Must be greater than or equal to startTimestamp; otherwise no events are returned
  • outputFormat: Output format. (JSON by default)

Events are returned from the most recent to the oldest.

Payload example

{
  "userId": "mock-user-id",
  "startTimestamp": 1788281445980,
  "endTimestamp": 1790873445980,
  "outputFormat": "json",
  "limit": 50
}

Responses

Correct response

Successful request

Describe the characteristics of a satisfactory response

200

Response structure:

type SearchEventsResponseType = {
  events: IEvent[] | string; // IEvent[] for "json", a CSV string for "csv"
};
Below we will describe the structure of the IEvent interface:
interface IEvent {
  timestamp: string; // Event date, format "YYYY-MM-DD HH:mm:ss.SSS" (not ISO 8601)
  eventName: string; // Event name, e.g. "Start medical report generation"
  userId: string;
  organizationId: string;
  metadata?: Record<string, string>; // Additional event-specific data. Only present when the event has it
}
Response body example (outputFormat: "json"):
{
  "events": [
    {
      "timestamp": "2026-10-01 14:30:04.741",
      "eventName": "Complete medical consultation",
      "userId": "mock-user-id",
      "organizationId": "mock-organization-id"
    }
  ]
}
Response body example (outputFormat: "csv"):The response is still a JSON object. The CSV, including its header row, is returned as a string in events:
{
  "events": "timestamp,eventName,userId,organizationId\n2026-10-01 14:30:04.741,Complete medical consultation,mock-user-id,mock-organization-id"
}
Description: when there are no events in the requested range, events is an empty array.

Wrong responses

Unauthorized request

Describe the characteristics of an unauthorized request

401

Response body

{
  "message": "Unauthorized"
}

Description: this error occurs when endpoint authorizers fail to validate the token sent in the request header.

Forbidden request

Describe the characteristics of an forbidden request

403

Response body

{
  "message": "Forbidden"
}

Description: this error occurs when your accessToken does not have permission to search for events related to this organization, for example when the user does not have the Organization Owner or Organization Admin role in the selected organization.

Bad request

Describe the characteristics of a bad request

400

Response body

type SearchEventErrorResponseType = {
  errorType: SEARCH_EVENT_ERROR_TYPE;
  errorMessage: string;
};

enum SEARCH_EVENT_ERROR_TYPE {
  INVALID_START_TIMESTAMP = "invalidStartTimestamp", // startTimestamp missing or not a number
  INVALID_END_TIMESTAMP = "invalidEndTimestamp",     // endTimestamp missing or not a number
  INVALID_LIMIT = "invalidLimitValue",               // limit not between 1 and 100, or not a number
  INVALID_OUTPUT_FORMAT = "invalidOutputFormat",     // outputFormat is not "json" or "csv"
}
Response body example:
{
  "errorMessage": "Limit must be between 1 and 100",
  "errorType": "invalidLimitValue"
}

Table of Contents