Skip to content
GetsitecontrolDevelopers

Widget statistics

GET
https://api.getsitecontrol.com/v1/sites/{site_id}/widgets/{widget_id}/stats
curl --request GET \
  --url 'https://api.getsitecontrol.com/v1/sites/1/widgets/1/stats?from=2026-04-15' \
  --header 'Authorization: Bearer <token>'

Event counts of one widget over the period. Counts: show is the widget shown to a visitor (a view), submit a form sent, openUrl a button or link opening a URL, showWidget a button opening another widget, addToCart, applyCoupon and copyToClipboard the matching cart and coupon buttons. rates next to each total gives every action counter divided by show, rounded to 4 places (rates.submit is the conversion rate); a rate is null when show is 0, as it is undefined, not zero.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
FieldDescription
site_id
required
Site Id
integer
widget_id
required
Widget Id

Widget id from List widgets

integer

Widget id from List widgets

Query Parameters

Section titled “Query Parameters”
FieldDescription
from
required
From

First day of the period, UTC, included

string format: date

First day of the period, UTC, included

to
To

Last day of the period, UTC, included; today when omitted

string format: date

Last day of the period, UTC, included; today when omitted

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
WidgetStatsTotal
object
FieldDescription
period
required
StatsPeriod
object
FieldDescription
date_from
required
Date From

First day, UTC, included

string format: date
date_to
required
Date To

Last day, UTC, included

string format: date
matched
Matched

How many live widgets the filters or ids matched; null without them. 0 means nothing matched, not that nothing happened: check the filters or ids

integer
nullable
total
required
WidgetMetrics

Event counts keyed by event type; every key is always present.

object
FieldDescription
show
required
Show
integer
submit
required
Submit
integer
openUrl
required
Openurl
integer
showWidget
required
Showwidget
integer
addToCart
required
Addtocart
integer
applyCoupon
required
Applycoupon
integer
copyToClipboard
required
Copytoclipboard
integer
rates
required
Rates

Each action counter of total divided by show, so the conversion rate is rates.submit; every key is always present, null when show is 0

object
FieldDescription
submit
Submit

submit / show; null when there were no shows: the rate is undefined, not zero

number
nullable
openUrl
Openurl

openUrl / show; null when there were no shows: the rate is undefined, not zero

number
nullable
showWidget
Showwidget

showWidget / show; null when there were no shows: the rate is undefined, not zero

number
nullable
addToCart
Addtocart

addToCart / show; null when there were no shows: the rate is undefined, not zero

number
nullable
applyCoupon
Applycoupon

applyCoupon / show; null when there were no shows: the rate is undefined, not zero

number
nullable
copyToClipboard
Copytoclipboard

copyToClipboard / show; null when there were no shows: the rate is undefined, not zero

number
nullable

Example · Generated

{
  "period": {
    "date_from": "2026-04-15",
    "date_to": "2026-04-15"
  },
  "matched": 1,
  "total": {
    "show": 1,
    "submit": 1,
    "openUrl": 1,
    "showWidget": 1,
    "addToCart": 1,
    "applyCoupon": 1,
    "copyToClipboard": 1
  },
  "rates": {
    "submit": 1,
    "openUrl": 1,
    "showWidget": 1,
    "addToCart": 1,
    "applyCoupon": 1,
    "copyToClipboard": 1
  }
}

Headers

Section titled “Headers”
FieldDescription
GSC-Version
string

API version the response was produced for

X-Request-Id
string

Request id, echoed from the request when valid

X-RateLimit-Limit
integer

Limit of the tightest bucket

X-RateLimit-Remaining
integer

Requests left in its window

X-RateLimit-Reset
integer

End of its window, epoch seconds

400

Section titled “400”

Unsupported GSC-Version

Media typeapplication/problem+json
Problem

The documented shape of every error body on the versioned surface.

object
FieldDescription
type
required
Type
string
title
required
Title
string
status
required
Status
integer
detail
Detail
string
nullable
instance
required
Instance
string
reason
Reason
string
nullable
next
Next
string
nullable
request_id
required
Request Id
string
errors
Errors
Array<object>
nullable
ValidationIssue
object
FieldDescription
loc
required
Loc
Array
msg
required
Msg
string
type
required
Type
string
metadata
Metadata
object

Example · Generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "reason": "example",
  "next": "example",
  "request_id": "example",
  "errors": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ],
  "metadata": {}
}

Headers

Section titled “Headers”
FieldDescription
GSC-Version
string

API version the response was produced for

X-Request-Id
string

Request id, echoed from the request when valid

X-RateLimit-Limit
integer

Limit of the tightest bucket

X-RateLimit-Remaining
integer

Requests left in its window

X-RateLimit-Reset
integer

End of its window, epoch seconds

401

Section titled “401”

Missing or invalid API key or access token

Media typeapplication/problem+json
Problem

The documented shape of every error body on the versioned surface.

object
FieldDescription
type
required
Type
string
title
required
Title
string
status
required
Status
integer
detail
Detail
string
nullable
instance
required
Instance
string
reason
Reason
string
nullable
next
Next
string
nullable
request_id
required
Request Id
string
errors
Errors
Array<object>
nullable
ValidationIssue
object
FieldDescription
loc
required
Loc
Array
msg
required
Msg
string
type
required
Type
string
metadata
Metadata
object

Example · Generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "reason": "example",
  "next": "example",
  "request_id": "example",
  "errors": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ],
  "metadata": {}
}

Headers

Section titled “Headers”
FieldDescription
GSC-Version
string

API version the response was produced for

X-Request-Id
string

Request id, echoed from the request when valid

X-RateLimit-Limit
integer

Limit of the tightest bucket

X-RateLimit-Remaining
integer

Requests left in its window

X-RateLimit-Reset
integer

End of its window, epoch seconds

WWW-Authenticate
string

Authentication scheme: Bearer

403

Section titled “403”

Access denied

Media typeapplication/problem+json
Problem

The documented shape of every error body on the versioned surface.

object
FieldDescription
type
required
Type
string
title
required
Title
string
status
required
Status
integer
detail
Detail
string
nullable
instance
required
Instance
string
reason
Reason
string
nullable
next
Next
string
nullable
request_id
required
Request Id
string
errors
Errors
Array<object>
nullable
ValidationIssue
object
FieldDescription
loc
required
Loc
Array
msg
required
Msg
string
type
required
Type
string
metadata
Metadata
object

Example · Generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "reason": "example",
  "next": "example",
  "request_id": "example",
  "errors": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ],
  "metadata": {}
}

Headers

Section titled “Headers”
FieldDescription
GSC-Version
string

API version the response was produced for

X-Request-Id
string

Request id, echoed from the request when valid

X-RateLimit-Limit
integer

Limit of the tightest bucket

X-RateLimit-Remaining
integer

Requests left in its window

X-RateLimit-Reset
integer

End of its window, epoch seconds

404

Section titled “404”

Not found

Media typeapplication/problem+json
Problem

The documented shape of every error body on the versioned surface.

object
FieldDescription
type
required
Type
string
title
required
Title
string
status
required
Status
integer
detail
Detail
string
nullable
instance
required
Instance
string
reason
Reason
string
nullable
next
Next
string
nullable
request_id
required
Request Id
string
errors
Errors
Array<object>
nullable
ValidationIssue
object
FieldDescription
loc
required
Loc
Array
msg
required
Msg
string
type
required
Type
string
metadata
Metadata
object

Example · Generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "reason": "example",
  "next": "example",
  "request_id": "example",
  "errors": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ],
  "metadata": {}
}

Headers

Section titled “Headers”
FieldDescription
GSC-Version
string

API version the response was produced for

X-Request-Id
string

Request id, echoed from the request when valid

X-RateLimit-Limit
integer

Limit of the tightest bucket

X-RateLimit-Remaining
integer

Requests left in its window

X-RateLimit-Reset
integer

End of its window, epoch seconds

422

Section titled “422”

Validation failed

Media typeapplication/problem+json
Problem

The documented shape of every error body on the versioned surface.

object
FieldDescription
type
required
Type
string
title
required
Title
string
status
required
Status
integer
detail
Detail
string
nullable
instance
required
Instance
string
reason
Reason
string
nullable
next
Next
string
nullable
request_id
required
Request Id
string
errors
Errors
Array<object>
nullable
ValidationIssue
object
FieldDescription
loc
required
Loc
Array
msg
required
Msg
string
type
required
Type
string
metadata
Metadata
object

Example · Generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "reason": "example",
  "next": "example",
  "request_id": "example",
  "errors": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ],
  "metadata": {}
}

Headers

Section titled “Headers”
FieldDescription
GSC-Version
string

API version the response was produced for

X-Request-Id
string

Request id, echoed from the request when valid

X-RateLimit-Limit
integer

Limit of the tightest bucket

X-RateLimit-Remaining
integer

Requests left in its window

X-RateLimit-Reset
integer

End of its window, epoch seconds

429

Section titled “429”

Rate limited

Media typeapplication/problem+json
Problem

The documented shape of every error body on the versioned surface.

object
FieldDescription
type
required
Type
string
title
required
Title
string
status
required
Status
integer
detail
Detail
string
nullable
instance
required
Instance
string
reason
Reason
string
nullable
next
Next
string
nullable
request_id
required
Request Id
string
errors
Errors
Array<object>
nullable
ValidationIssue
object
FieldDescription
loc
required
Loc
Array
msg
required
Msg
string
type
required
Type
string
metadata
Metadata
object

Example · Generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "reason": "example",
  "next": "example",
  "request_id": "example",
  "errors": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ],
  "metadata": {}
}

Headers

Section titled “Headers”
FieldDescription
GSC-Version
string

API version the response was produced for

X-Request-Id
string

Request id, echoed from the request when valid

X-RateLimit-Limit
integer

Limit of the tightest bucket

X-RateLimit-Remaining
integer

Requests left in its window

X-RateLimit-Reset
integer

End of its window, epoch seconds

Retry-After
integer

Seconds until the bucket refills

503

Section titled “503”
Media typeapplication/problem+json

temporarily_unavailable: the statistics store timed out or is overloaded; the heavy request is spent all the same

Problem

The documented shape of every error body on the versioned surface.

object
FieldDescription
type
required
Type
string
title
required
Title
string
status
required
Status
integer
detail
Detail
string
nullable
instance
required
Instance
string
reason
Reason
string
nullable
next
Next
string
nullable
request_id
required
Request Id
string
errors
Errors
Array<object>
nullable
ValidationIssue
object
FieldDescription
loc
required
Loc
Array
msg
required
Msg
string
type
required
Type
string
metadata
Metadata
object

Example · Generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "reason": "example",
  "next": "example",
  "request_id": "example",
  "errors": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ],
  "metadata": {}
}

Headers

Section titled “Headers”
FieldDescription
GSC-Version
string

API version the response was produced for

X-Request-Id
string

Request id, echoed from the request when valid

X-RateLimit-Limit
integer

Limit of the tightest bucket

X-RateLimit-Remaining
integer

Requests left in its window

X-RateLimit-Reset
integer

End of its window, epoch seconds

llms.txtOpenAPI