Endpoints

The base URL for the Widged API is https://api.widged.io/.

Retrieve a single event by id

Provides information about the event.

GET /v1/events/:id

Path Parameters

id — Unique identifier of the event (evt).

Response

• HTTP 200 - Returns a JSON object representing the event.
• HTTP 404 - Event not found.

Example response (200)

{
    "id": "evt_s_UsiKbXy_pDhUmVgkAJiN4bba1ihMmixX8iZp55AU",
    "name": "widget_flow_widget_shown",
    "createdAt": "2025-08-02T12:34:56.789Z",
    "widgetId": "qwertyui",
    "sessionId": "ses_c_UsiKaep_2ShcvvEjwZyln1nD9Ycdq0t4hYNvO1Ih",
    "pageloadId": "pgld_c_UsiKaeo_Pj6RxE0XtY2RFKqgWHYGZgmipan0AI8g",
    "leadId": "lead_c_UhgTDnj_TxoTFB5q8kTNR5xZvukWeXdT0SJDVRFh",
    "payload": {
        "url": "https://widged.io/",
        "time": "2025-08-02T12:34:56.789Z"
    }
}

Retrieve a single collected record by id

Provides information about the collected record.

GET /v1/records/:id

Path Parameters

id — Unique identifier of the record (rec).

Response

• HTTP 200 - Returns a JSON object representing the collected record.
• HTTP 404 - Event not found.

Example response (200)

{
    "id": "rec_s_UsiL2d8_VqVlXCLEHK91xHp4E7NHMZ6bVH34kSzu",
    "createdAt": "2025-08-02T12:34:56.789Z",
    "widgetId": "qwertyui",
    "sessionId": "ses_c_UsiL1Tr_Ms3jWBBg4rcIJazBUSktOezdAhgTPKJu",
    "pageloadId": "pgld_c_UsiL1Tq_2NjALQTlTdSmysNaqytyAW1C03ItYiYq",
    "leadId": "lead_c_UhgTDnj_TxoTFB5q8kTNR5xZvukWeXdT0SJDVRFh",
    "partition": "Fierce Kangaroo 5037",
    "data": {
        "First Name": "John",
        "Last Name": "Doe"
    }
}

Search events

Provides information about the events matching your request.

POST /v1/events/search

Request

See search request.

Parameter	Supported operators	Description
id	eq, neq	Unique identifier of the event (evt)
createdAt	gt, gte, lt, lte	When the event was created
sessionId	eq, neq	Unique identifier of the session (ses)
pageloadId	eq, neq	Unique identifier of the pageload (pgld)
leadId	eq, neq	Unique identifier of the lead (lead)
name	eq, neq	Name of the event (see Events)

Response

• HTTP 200 - Returns a JSON object with the following fields:
  • objects – a list of matching items;
  • total – the total number of items matching your query.
• HTTP 400 - Request is not valid (for example, not a valid JSON).
• HTTP 422 - Something wrong with your request (see error message).

Example response (200)

{
    "objects": [
        {
            "id": "evt_s_UsiKbXy_pDhUmVgkAJiN4bba1ihMmixX8iZp55AU",
            "name": "widget_flow_widget_shown",
            "createdAt": "2025-08-02T12:34:56.789Z",
            "widgetId": "qwertyui",
            "sessionId": "ses_c_UsiKaep_2ShcvvEjwZyln1nD9Ycdq0t4hYNvO1Ih",
            "pageloadId": "pgld_c_UsiKaeo_Pj6RxE0XtY2RFKqgWHYGZgmipan0AI8g",
            "leadId": "lead_c_UhgTDnj_TxoTFB5q8kTNR5xZvukWeXdT0SJDVRFh",
            "payload": {
                "url": "https://widged.io/",
                "time": "2025-08-02T12:34:56.789Z"
            }
        },
        ...
    ],
    "total": 999
}

Search collected records

Provides information about the collected records matching your request.

POST /v1/records/search

Request

See search request.

Parameter	Supported operators	Description
id	eq, neq	Unique identifier of the record (rec)
createdAt	gt, gte, lt, lte	When the record was created
sessionId	eq, neq	Unique identifier of the session (ses)
pageloadId	eq, neq	Unique identifier of the pageload (pgld)
leadId	eq, neq	Unique identifier of the lead (lead)
partition	eq, neq	Name of the partition
data	like, nlike	Collected record data
data.*	eq, neq	Collected record data (one specific property)

Response

• HTTP 200 - Returns a JSON object with the following fields:
  • objects – a list of matching items;
  • total – the total number of items matching your query.
• HTTP 400 - Request is not valid (for example, not a valid JSON).
• HTTP 422 - Something wrong with your request (see error message).

Example response (200)

{
    "objects": [
        {
            "id": "rec_s_UsiL2d8_VqVlXCLEHK91xHp4E7NHMZ6bVH34kSzu",
            "createdAt": "2025-08-02T12:34:56.789Z",
            "widgetId": "qwertyui",
            "sessionId": "ses_c_UsiL1Tr_Ms3jWBBg4rcIJazBUSktOezdAhgTPKJu",
            "pageloadId": "pgld_c_UsiL1Tq_2NjALQTlTdSmysNaqytyAW1C03ItYiYq",
            "leadId": "lead_c_UhgTDnj_TxoTFB5q8kTNR5xZvukWeXdT0SJDVRFh",
            "partition": "Fierce Kangaroo 5037",
            "data": {
                "First Name": "John",
                "Last Name": "Doe"
            }
        },
        ...
    ],
    "total": 999
}