Need Help?

Analytics API Guide

Last Updated: Jan 19, 2016

This page provides an overview of how to use the Analytics API. Complete documentation for the API endpoints is available at

There exist API clients in several languages already. The following clients are provided by Luminoso:


Almost every response from the API will be a JSON-encoded dictionary with keys "result" and "error". For a successful API call, the value of "error" will be null, and the value of "result" will be whatever the documentation says the endpoint returns. For an unsuccessful API call, the value of "result" will be null, and the value of "error" will be a dictionary with keys "code" and "message", which describe what the error was. (See API Error Codes for more information about the codes.)

Example successful response body:

	"result": "User created.",
	"error": null

Example unsuccessful response body:

 "result": null,
 "error": {
           "message": "The parameter terms should be a list of strings.",
           "code": "NOT_A_STR_LIST"

There are three exceptions to this result format:

  • The root URL returns API documentation as plaintext.
  • Several endpoints return CSV files by default. This is specified in their documentation.  (You can also pass a parameter to make them return XLSX files or JSON instead.)
  • If the server is somehow misconfigured and the request never even gets to the API, it is possible that the response could be an HTML error page.

Responses will also have appropriate HTTP status codes. Successful API calls will return responses with status code 200 or 201, and unsuccessful API calls will return responses with status codes of 400 or higher. But in general, the HTTP status codes are less informative than the error code and message contained in the response body.


Sending parameters

For GET and DELETE requests, there is no request body, and any request parameters must be put into the query string.

For POST, PUT, and PATCH requests, the parameters should be put into a form as the request body, and the content-type header of the request must be application/x-www-form-urlencoded (it is likely that the client library for sending HTTP requests in your language of choice will automatically set this content-type). There is one exception, which is for uploading content (see Uploading below).

The values of all parameters except strings should be JSON-encoded. The documentation for the API endpoints generally specifies what type it is expecting for each parameter (string, number, list, dictionary, etc.); sometimes it specifies that the value should be JSON-encoded and sometimes it doesn't, but it always should be unless it's already a string.


In most POST, PUT, and PATCH requests, the parameters go in the request body, and the content-type header of the request is application/x-www-form-urlencoded. There is one exception to this rule, which is when the API call is uploading a file (currently the only file uploads we support are JSON documents, which will have content-type application/json). In this case, the request body will consist entirely of the content being uploaded, and all request parameters must be sent as URL parameters.


Requests to the Analytics API are authenticated by passing a token in the Authorization header.

Obtaining a token

There are two types of API tokens: long-lived and short-lived. Both types provide the same authorizations (the things that a user is allowed to do are the same regardless of whether he authenticates using a long-lived token or a short-lived token), but they are intended for different use cases.

Long-lived tokens:

  • Intended for programmatic API usage
  • Never expire
  • Each user can have at most one
  • Obtained using POST /v4/user/tokens/*
  • Can be deleted using DELETE /v4/user/tokens/<token>/*
* The requests to create or delete a long-lived token must be authenticated using a short-lived token.

Short-lived tokens:

  • Intended for usage in the Analytics UI or other cases where logging out is desired
  • Expire after some amount of time (two weeks by default)
  • Each user can have many (one per logged-in session)
  • Obtained using POST /v4/user/login/ with a username and password
  • Can be deleted using POST /v4/user/logout/ (to delete the token you're currently using) or DELETE /v4/user/tokens/<token>/ (to delete any other token)

For more details about tokens, refer to the API documentation.

Authenticating with a token

To be authenticated, each request must include an "Authorization" header whose value is "Token " plus the token. For example, if your token is SMHbb4zYTOXjuw2RkMOspAkWGFAQ1twV, then the request should have an "Authorization" header with the value Token SMHbb4zYTOXjuw2RkMOspAkWGFAQ1twV. (Note that the name of the header is "Authorization", NOT "Authentication".)

More Support
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found