Skip to content
Menu
SilktideDevelopers

Get how long visits lasted, step by step over a period

GET/v1/results/analytics/duration-over-time
View as Markdown

Returns how long the average visit lasted in each step of a period, and across the whole of it, for an analytics view or a website.

Duration is engaged time: the seconds the visitor was actively using the pages of a visit, not how long a tab stayed open. Some visits record more engaged time than one person could have spent in them, such as colleagues behind one office network who look like a single visitor, or a computer that slept with the page open. Those are left out of the average and counted in unmeasuredSessions, with their page views in unmeasuredPageViews, so you can tell how much of the traffic the average does not cover. They are still visits, in totalSessions.

total weights each step by its measured visits, so do not average the steps to get it.

The old documentation named the average observedDuration. It is engagedDuration.

Send a period. With the default, all, this answers with an error. How long each step is, and how to choose it, is under Over time. A filters[url] filter matches the page each visit started on. Traffic collected at the Basic consent level records no visits, so it is not counted here.

Request
curl "https://api.eu.silktide.com/v1/results/analytics/duration-over-time?view=all&period=custom&from=2026-10-01&to=2026-10-03" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY"
Response: Average visit length each day
{
  "result": {
    "series": [
      {
        "time": "2026-10-01 00:00:00",
        "engagedDuration": 54,
        "totalSessions": 244,
        "measuredSessions": 243,
        "unmeasuredSessions": 1,
        "sessionPageViews": 546,
        "unmeasuredPageViews": 12
      },
      {
        "time": "2026-10-02 00:00:00",
        "engagedDuration": 58,
        "totalSessions": 254,
        "measuredSessions": 254,
        "unmeasuredSessions": 0,
        "sessionPageViews": 586,
        "unmeasuredPageViews": 0
      },
      {
        "time": "2026-10-03 00:00:00",
        "engagedDuration": 62,
        "totalSessions": 236,
        "measuredSessions": 236,
        "unmeasuredSessions": 0,
        "sessionPageViews": 670,
        "unmeasuredPageViews": 0
      }
    ],
    "total": 57.96180081855389,
    "range": {
      "start": "2026-10-01 00:00:00",
      "end": "2026-10-04 00:00:00"
    }
  },
  "selector": "/v1/results/analytics/duration-over-time",
  "duration": 0.011
}

Request

Query parameters

  • viewstringmatches ^(all|[1-9]\d*)$

    The analytics view to read: its id, the number after /analytics/ in its address in Silktide, or all for all of the account's analytics. Send this or websiteId.

  • websiteIdintegerat least 1

    Instead of view, a website whose analytics to read. The website must have Analytics set up.

  • sectionIdinteger

    With websiteId, a section of the website. Defaults to 0, the whole website.

  • periodstring

    The date range. Defaults to all. The spaced forms (-7 days, month to date) are older names that keep working. custom needs from and to.

    One ofalltodaylast-7-dayslast-30-dayslast-90-daysmonth-to-datelast-monthyear-to-datelast-12-monthscustom-7 days-30 days-90 days-1 monthmonth to dateyear to date-12 months

  • fromstring

    With period=custom, the first day, such as 2026-10-01.

  • tostring

    With period=custom, the last day.

  • timezonestring

    The IANA time zone days are read in, such as America/New_York. Defaults to UTC.

  • filtersmap of strings

    Only visits matching every filter, keyed by what is filtered: filters[url]=contains:/blog. Each value is {operator}:{value}, with operator is, not, contains, starts, gt or lt. Keys include url, hostName, entryUrl, exitUrl, event, outgoingUrl, referrer, source, medium, campaign, content, term, countryCode, regionCode, language, deviceType (desktop, tablet or mobile), operatingSystem and browser.

  • intervalstring

    With period=custom, the length of each step: an hour, a day, a week starting on Monday, a month or a year. Ignored with any other period. Left out, steps are hours for a single day, months for exactly twelve months, and days otherwise.

    One ofPT1HP1DP7DP1MP1Y

  • previousPeriodstring

    1 to add the figures of the period before, the same length and ending where this one starts, as previous… fields. Left out or 0, none. Needs a period with a start: with all, nothing is added.

    One of01

Response

200JSON.

  • resultobjectrequired

    The answer.

    Show 4 fields
    • serieslist of objectsrequired

      One step per hour, day, week or month of the period, oldest first. A step with no visits reads 0 throughout.

      Show 13 fields
      • timestringrequiredmatches ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$

        When the step starts, as YYYY-MM-DD HH:MM:SS in the request's timezone.

      • engagedDurationintegerrequired

        The average seconds a visit in the step was actively used, over its measured visits, rounded to a whole second. 0 when it had none.

      • totalSessionsintegerrequired

        Every visit in the step.

      • measuredSessionsintegerrequired

        The visits the average is over.

      • unmeasuredSessionsintegerrequired

        Visits left out of the average because their engaged time could not be one person's.

      • sessionPageViewsintegerrequired

        Page views in all of the step's visits.

      • unmeasuredPageViewsintegerrequired

        Page views in the visits left out of the average.

      • previousEngagedDurationintegercan be null

        The average engaged seconds in the matching step of the period before. Only with previousPeriod=1. Null when that period has no step in the same place, which weekly and monthly steps can cause.

      • previousTotalSessionsintegercan be null

        Every visit in the matching step of the period before. Only with previousPeriod=1. Null when that period has no step in the same place, which weekly and monthly steps can cause.

      • previousMeasuredSessionsintegercan be null

        Measured visits in the matching step of the period before. Only with previousPeriod=1. Null when that period has no step in the same place, which weekly and monthly steps can cause.

      • previousUnmeasuredSessionsintegercan be null

        Visits left out in the matching step of the period before. Only with previousPeriod=1. Null when that period has no step in the same place, which weekly and monthly steps can cause.

      • previousSessionPageViewsintegercan be null

        Page views in visits in the matching step of the period before. Only with previousPeriod=1. Null when that period has no step in the same place, which weekly and monthly steps can cause.

      • previousUnmeasuredPageViewsintegercan be null

        Page views in visits left out in the matching step of the period before. Only with previousPeriod=1. Null when that period has no step in the same place, which weekly and monthly steps can cause.

    • totalnumberrequired

      The average engaged seconds of a visit across the whole period, not rounded: each step's average weighted by its measured visits.

    • rangeobjectrequired

      The dates the series covers.

      Show 2 fields
      • startstringrequiredmatches ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$

        When the first step starts, as YYYY-MM-DD HH:MM:SS in the request's timezone.

      • endstringrequiredmatches ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$

        When the range ends, as YYYY-MM-DD HH:MM:SS: midnight after its last day, so the range runs up to but not including it.

    • previousTotalnumber

      The same average across the period before. Only with previousPeriod=1.

  • selectorstringrequired

    The query that answered, as its path: /v1/results/scores.

  • durationnumberrequired

    Seconds Silktide took to answer.

Errors

StatusTypeWhen
404ModelNotFoundNo view or website with that id exists in the account, or the API key's user cannot see it.
403AccessDeniedThe API key's user cannot read that analytics view.
200ModelNotFoundThe website has no Analytics set up. The body is an error despite the status.
200InvalidRequestNeither view nor websiteId was sent. The error's own status is 400 and properties.field is view. The body is an error despite the status.
200InvalidArgumentA filter names a key or operator Analytics does not know. The body is an error despite the status.
200Errorperiod is all or left out, which means all. Over-time queries need a period with a start. The body is an error despite the status.
200InvalidArgumentperiod is not one of its values, or is custom without both from and to. The body is an error despite the status.
200Unspecifiedinterval is not one of its values. The body is an error despite the status.
401NotLoggedInNo API key was sent, or it is not a key for this region.(any operation)
429TooManyRequestsToo many requests to this path in five seconds. Retry after the number of seconds in the Retry-After header, which properties.retryAfter repeats.(any operation)
503-Silktide is busy. Retry after the number of seconds in the Retry-After header.(any operation)

Every error has the same body. See Errors.

Access

Permission
View analytics view (View all analytics for `view=all`)
Plan feature
None
Edition
Silktide 4 and Silktide 5
Cost
Free
Available since
v1.0.0

Try it

Sends a real request to your account from this browser. Your key stays in this tab and goes only to the Silktide API.