Skip to main content
Support

Retrieve the most-viewed articles

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

Example request

Generated
Parameters
curl 'https://api.helpdocs.io/v1/stats/article?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' \
  -H 'Authorization: Bearer YOUR_TOKEN'
curl https://api.helpdocs.io/v1/stats/article \
  -H 'Authorization: Bearer YOUR_TOKEN'
const url = "https://api.helpdocs.io/v1/stats/article?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";

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/article";

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/article?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";

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/article";

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/article"

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",
}

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

print(response.json())
import requests

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

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

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

print(response.json())
<?php

$ch = curl_init("https://api.helpdocs.io/v1/stats/article?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");

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/article");

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/article?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", 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/article", 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/article?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"))
            .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/article"))
            .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/article?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")

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/article")

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/article?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");
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/article");
request.Headers.Add("Authorization", "Bearer YOUR_TOKEN");

var response = await client.SendAsync(request);

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

Responses

{
  "top_articles": [
    {
      "article_id": "string",
      "title": "string",
      "count": 1
    }
  ]
}

The most-viewed articles

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 view counts over a time window. Responses are cached, so a request repeated inside the cache window returns the same figures.

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 9
  • 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"

Responses

200

The most-viewed articles

application/json TopArticlesResponse
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