Skip to main content
Support

Retrieve readership over time

GET https://api.helpdocs.io/v1/stats/graph

Example request

Generated
Parameters
curl 'https://api.helpdocs.io/v1/stats/graph?start=string&end=string&limit=1&category_id=string&language_code=string&is_bot=true&spam_filter=true&article_id=string&user_id=string&group_id=string&group_by=string&anonymous_only=true&exclude_ip=string&data_source=api&exact_sessions=true' \
  -H 'Authorization: Bearer YOUR_TOKEN'
curl https://api.helpdocs.io/v1/stats/graph \
  -H 'Authorization: Bearer YOUR_TOKEN'
const url = "https://api.helpdocs.io/v1/stats/graph?start=string&end=string&limit=1&category_id=string&language_code=string&is_bot=true&spam_filter=true&article_id=string&user_id=string&group_id=string&group_by=string&anonymous_only=true&exclude_ip=string&data_source=api&exact_sessions=true";

const response = await fetch(url, {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  },
});

const data = await response.json();
console.log(data);
const url = "https://api.helpdocs.io/v1/stats/graph";

const response = await fetch(url, {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  },
});

const data = await response.json();
console.log(data);
const url = "https://api.helpdocs.io/v1/stats/graph?start=string&end=string&limit=1&category_id=string&language_code=string&is_bot=true&spam_filter=true&article_id=string&user_id=string&group_id=string&group_by=string&anonymous_only=true&exclude_ip=string&data_source=api&exact_sessions=true";

const options: RequestInit = {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  },
};

const response = await fetch(url, options);

const data: unknown = await response.json();
console.log(data);
const url = "https://api.helpdocs.io/v1/stats/graph";

const options: RequestInit = {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  },
};

const response = await fetch(url, options);

const data: unknown = await response.json();
console.log(data);
import requests

url = "https://api.helpdocs.io/v1/stats/graph"

headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}

params = {
    "start": "string",
    "end": "string",
    "limit": "1",
    "category_id": "string",
    "language_code": "string",
    "is_bot": "true",
    "spam_filter": "true",
    "article_id": "string",
    "user_id": "string",
    "group_id": "string",
    "group_by": "string",
    "anonymous_only": "true",
    "exclude_ip": "string",
    "data_source": "api",
    "exact_sessions": "true",
}

response = requests.get(url, headers=headers, params=params)

print(response.json())
import requests

url = "https://api.helpdocs.io/v1/stats/graph"

headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}

response = requests.get(url, headers=headers)

print(response.json())
<?php

$ch = curl_init("https://api.helpdocs.io/v1/stats/graph?start=string&end=string&limit=1&category_id=string&language_code=string&is_bot=true&spam_filter=true&article_id=string&user_id=string&group_id=string&group_by=string&anonymous_only=true&exclude_ip=string&data_source=api&exact_sessions=true");

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_TOKEN",
    ],
]);

$response = curl_exec($ch);

print_r(json_decode($response, true));
<?php

$ch = curl_init("https://api.helpdocs.io/v1/stats/graph");

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_TOKEN",
    ],
]);

$response = curl_exec($ch);

print_r(json_decode($response, true));
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://api.helpdocs.io/v1/stats/graph?start=string&end=string&limit=1&category_id=string&language_code=string&is_bot=true&spam_filter=true&article_id=string&user_id=string&group_id=string&group_by=string&anonymous_only=true&exclude_ip=string&data_source=api&exact_sessions=true", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_TOKEN")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(data))
}
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://api.helpdocs.io/v1/stats/graph", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_TOKEN")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(data))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.helpdocs.io/v1/stats/graph?start=string&end=string&limit=1&category_id=string&language_code=string&is_bot=true&spam_filter=true&article_id=string&user_id=string&group_id=string&group_by=string&anonymous_only=true&exclude_ip=string&data_source=api&exact_sessions=true"))
            .header("Authorization", "Bearer YOUR_TOKEN")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.helpdocs.io/v1/stats/graph"))
            .header("Authorization", "Bearer YOUR_TOKEN")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}
require "json"
require "net/http"

uri = URI("https://api.helpdocs.io/v1/stats/graph?start=string&end=string&limit=1&category_id=string&language_code=string&is_bot=true&spam_filter=true&article_id=string&user_id=string&group_id=string&group_by=string&anonymous_only=true&exclude_ip=string&data_source=api&exact_sessions=true")

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_TOKEN"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

pp JSON.parse(response.body)
require "json"
require "net/http"

uri = URI("https://api.helpdocs.io/v1/stats/graph")

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_TOKEN"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

pp JSON.parse(response.body)
var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.helpdocs.io/v1/stats/graph?start=string&end=string&limit=1&category_id=string&language_code=string&is_bot=true&spam_filter=true&article_id=string&user_id=string&group_id=string&group_by=string&anonymous_only=true&exclude_ip=string&data_source=api&exact_sessions=true");
request.Headers.Add("Authorization", "Bearer YOUR_TOKEN");

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());
var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.helpdocs.io/v1/stats/graph");
request.Headers.Add("Authorization", "Bearer YOUR_TOKEN");

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Responses

{
  "articleviews": [
    {
      "date_string": "string",
      "date": 1.5,
      "article_id": "string",
      "category_id": "string",
      "user_id": "string",
      "user_agent_browser": "string",
      "user_agent_os": "string",
      "ip_range": "string",
      "count": 1,
      "sessions": 1
    }
  ],
  "searches": [
    {
      "date_string": "string",
      "date": 1.5,
      "article_id": "string",
      "category_id": "string",
      "user_id": "string",
      "user_agent_browser": "string",
      "user_agent_os": "string",
      "ip_range": "string",
      "count": 1,
      "sessions": 1
    }
  ],
  "contacts": [
    {
      "date_string": "string",
      "date": 1.5,
      "article_id": "string",
      "category_id": "string",
      "user_id": "string",
      "user_agent_browser": "string",
      "user_agent_os": "string",
      "ip_range": "string",
      "count": 1,
      "sessions": 1
    }
  ]
}

The three series.

Schemas
{
  "code": 1,
  "err": "string"
}

Authentication failed or no API key was supplied.

Schemas
{
  "code": 1,
  "err": "string"
}

The key lacks read permission, or the account’s plan does not include API access.

Schemas
{
  "code": 1,
  "err": "string"
}

Rate limited. Wait the number of seconds in Retry-After before trying again. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset say which allowance was spent and when it refills.

Schemas
Generated

Article views, searches, and contact submissions across the window, as three series. Days with no activity are filled in with zeroes, so the series are continuous.

Authentication

    • ApiKeyBearer http bearer

      An API key sent as Authorization: Bearer <key>. A key holds scopes, the same ones OAuth uses, and an operation needs the scope listed for it under OAuth2. A key may also expire, or be revoked or rotated in Settings > API, after which it is refused with a 401.

    • OAuth2 oauth2

      An OAuth 2.0 access token for an app acting on behalf of a HelpDocs user, sent as Authorization: Bearer <token>. The authorization code flow requires PKCE (S256). Each operation names the one scope it needs.

      Scopes read:analytics

Query parameters

  • start string

    Start of the window (RFC 3339). Defaults to the last 30 days.

  • end string

    End of the window (RFC 3339).

  • limit integer

    Maximum number of articles to return.

  • category_id string

    Restrict to articles in this category.

  • language_code string

    Restrict to this translation.

See more 10
  • is_bot boolean

    Include views attributed to bots.

  • spam_filter boolean

    Exclude views classified as spam.

  • article_id string

    Restrict to these articles. Accepts a comma-separated list of ids.

  • user_id string

    Restrict to views by these users. Accepts a comma-separated list of ids.

  • group_id string

    Restrict to readers in this permission group.

  • group_by string

    The dimension to group by. Defaults to date_string, which gives a daily series; article_id, category_id, user_id, user_agent_browser, user_agent_os, and ip_range group by that field instead.

  • anonymous_only boolean

    Only views by readers who were not signed in.

  • exclude_ip string

    Ignore views from these addresses. Accepts a comma-separated list.

  • data_source string

    Only count events from this surface. An unrecognised value is ignored, which counts every surface.

    enum "api""subdomain""custom_domain""lighthouse""intercom""front"

  • exact_sessions boolean

    Count sessions exactly rather than with the approximate estimator. Accurate but slower on large accounts.

Responses

200

The three series.

application/json AnalyticsGraphResponse
401

Authentication failed or no API key was supplied.

application/json Error

An error response.

  • code integer Required

    The HTTP status code.

  • err string Required

    A human-readable description of the failure.

403

The key lacks read permission, or the account’s plan does not include API access.

application/json Error

An error response.

  • code integer Required

    The HTTP status code.

  • err string Required

    A human-readable description of the failure.

429

Rate limited. Wait the number of seconds in Retry-After before trying again. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset say which allowance was spent and when it refills.

headers

  • Retry-After integer
  • X-RateLimit-Limit integer
  • X-RateLimit-Remaining integer
  • X-RateLimit-Reset integer
application/json Error

An error response.

  • code integer Required

    The HTTP status code.

  • err string Required

    A human-readable description of the failure.

All endpoints