Get new and returning visitor analytics

Returns visitor acquisition and browsing metrics for the selected range.

GET/api/analytics/visitors

Returns visitor acquisition and browsing metrics for the selected range. The response compares new and returning visitors, lists the most common current pages, and returns an empty geo array when country data is unavailable. To use custom dates, send both start and end as ISO 8601 datetimes with offsets. Explicit boundaries override range; a single boundary is rejected. Date buckets are calculated in UTC. Periods with no data return the documented empty or zero-value response. Endpoints that support format=csv return a text/csv download. CSV export may require an eligible plan; JSON is the default.

pages.docs.apiRequirements.title

pages.docs.apiRequirements.credentials: pages.docs.apiRequirements.credentialsIntro pages.docs.apiRequirements.bearerApiKey pages.docs.apiRequirements.or pages.docs.apiRequirements.apiKeyHeader.
pages.docs.apiRequirements.scope: analytics:read
pages.docs.apiRequirements.module: pages.docs.apiRequirements.automationApiModule (automation_api)
pages.docs.apiRequirements.tenantScope: Requests can access only resources owned by the authenticated organization. The API does not reveal whether an identifier belongs to another organization or site.
pages.docs.apiRequirements.retryBehavior: pages.docs.apiRequirements.retryModes.safeRead: You can safely retry this read-only request after a transport failure. It does not change resource state.

Query Parameters

range?string

Query parameter. Range. Allowed values: 7d, 30d, 90d.

start?string

Query parameter. ISO 8601 date and time for start.

end?string

Query parameter. ISO 8601 date and time for end.

Response Body

`application/json`

{
  "newVsReturning": [
    {
      "name": "New",
      "value": 42
    },
    {
      "name": "Returning",
      "value": 17
    }
  ],
  "topPages": [
    {
      "page": "/pricing",
      "views": 21
    }
  ],
  "geo": []
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

Request examples

curl

curl --request GET \
  'https://api.convor.io/api/analytics/visitors' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer convor_sk_...'

JavaScript

const response = await fetch("https://api.convor.io/api/analytics/visitors", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer convor_sk_..."
  },
});

const contentType = response.headers.get("content-type") ?? "";
const data = response.status === 204
  ? null
  : contentType.includes("json")
    ? await response.json()
    : contentType.startsWith("text/")
      ? await response.text()
      : await response.blob();

if (!response.ok) {
  const message = typeof data === "object" && data !== null
    && "error" in data && typeof data.error === "object"
    && data.error !== null && "message" in data.error
      ? String(data.error.message)
      : "Convor API request failed (" + response.status + ")";
  throw new Error(message);
}

console.log(data);

Was this page helpful?

Get new and returning visitor analytics

Returns visitor acquisition and browsing metrics for the selected range.

GET/api/analytics/visitors

pages.docs.apiRequirements.title

pages.docs.apiRequirements.credentials: pages.docs.apiRequirements.credentialsIntro pages.docs.apiRequirements.bearerApiKey pages.docs.apiRequirements.or pages.docs.apiRequirements.apiKeyHeader.
pages.docs.apiRequirements.scope: analytics:read
pages.docs.apiRequirements.module: pages.docs.apiRequirements.automationApiModule (automation_api)
pages.docs.apiRequirements.tenantScope: Requests can access only resources owned by the authenticated organization. The API does not reveal whether an identifier belongs to another organization or site.
pages.docs.apiRequirements.retryBehavior: pages.docs.apiRequirements.retryModes.safeRead: You can safely retry this read-only request after a transport failure. It does not change resource state.

Query Parameters

range?string

Query parameter. Range. Allowed values: 7d, 30d, 90d.

start?string

Query parameter. ISO 8601 date and time for start.

end?string

Query parameter. ISO 8601 date and time for end.

Response Body

`application/json`

{
  "newVsReturning": [
    {
      "name": "New",
      "value": 42
    },
    {
      "name": "Returning",
      "value": 17
    }
  ],
  "topPages": [
    {
      "page": "/pricing",
      "views": 21
    }
  ],
  "geo": []
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

Request examples

curl

curl --request GET \
  'https://api.convor.io/api/analytics/visitors' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer convor_sk_...'

JavaScript

const response = await fetch("https://api.convor.io/api/analytics/visitors", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer convor_sk_..."
  },
});

const contentType = response.headers.get("content-type") ?? "";
const data = response.status === 204
  ? null
  : contentType.includes("json")
    ? await response.json()
    : contentType.startsWith("text/")
      ? await response.text()
      : await response.blob();

if (!response.ok) {
  const message = typeof data === "object" && data !== null
    && "error" in data && typeof data.error === "object"
    && data.error !== null && "message" in data.error
      ? String(data.error.message)
      : "Convor API request failed (" + response.status + ")";
  throw new Error(message);
}

console.log(data);

Was this page helpful?

Get new and returning visitor analytics

pages.docs.apiRequirements.title

Query Parameters

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Request examples

curl

JavaScript

On this page

Get new and returning visitor analytics

pages.docs.apiRequirements.title

Query Parameters

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Request examples

curl

JavaScript

On this page

Get new and returning visitor analytics

pages.docs.apiRequirements.title

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

On this page

Get new and returning visitor analytics

pages.docs.apiRequirements.title

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`