Introduction

The quintly API is made for you to access all data points you already know from our tool. You need to have a quintly business account in order to access this API. Please get in touch with our support if you like to get access.

Authentication

For authentication we use Basic Auth via HTTPS. For the username you have to send your quintly client id and for the password your API secret. If you don't have these details yet, please get in touch with our support.

Managing your profiles

There is full support to list, add and remove profiles within your account via the API.

Please use the following endpoint for listing all profiles within your account. Here you can also obtain the profile ids necessary to fetch data later on. 

https://api.quintly.com/v0.9/list-profiles

For adding profiles, please specify the space id (which you'll get from our support team once access to our API is granted), and a unique URL for the profile to be added. Usually you will use the search endpoint described below to identify the unique URL of a profile. 

https://api.quintly.com/v0.9/add-profile?spaceId=1&q=https%3A%2F%2Fwww.facebook.com%2Fquintly

To remove an existing profile from your account, just provide the space id and the profile id (which can be obtained via the list-profiles endpoint described above). 

https://api.quintly.com/v0.9/remove-profile?spaceId=1&profileId=92

Usually before adding a new profile you will need to uniquely identify a profile. For this use case and also to search profiles via all the search endpoints of the networks itself, you can use the following endpoint for search. 

https://api.quintly.com/v0.9/search-profiles?q=quintly
https://api.quintly.com/v0.9/search-profiles?q=quintly&network=facebook
https://api.quintly.com/v0.9/search-profiles?q=https%3A%2F%2Fwww.facebook.com%2Fquintly

Fetching data

Loading data is handled via the qql endpoint. We recommend using the Metric Builder to easily build API requests. After you pressed Run QQL within Metric Builder, there is an API section within the Query results tab holding the complete API request for this metric and the current selection (profile, date and additional filters).

The qql endpoint considers the following parameters:

  • qqlQuery: The QQL query describing the data to be loaded. Find further information on how to write QQL queries in our knowledge base.
  • startTime: The beginning of the period you want to get the data for in format YYYY-MM-DD
  • endTime: The end of the period you want to get the data for in format YYYY-MM-DD
  • interval: The aggregation interval used for the analysis (daily, weekly, monthly, yearly, total)
  • timezone (optional): By default our API does fetch and aggregate data using the timezone setting of the admin user of your quintly account. We strongly recommend to set an explicit timezone to not rely on settings of one of your users. The list of supported timezones can be found here. E.g. for fetching data in UTC timezone just use "UTC" here.
  • profileIds: A comma-separated list of profile ids (you can find the id of a profile by using the list-profiles endpoint described above). You can only fetch data for profiles added to your quintly account.
  • postTags (optional): A configuration in JSON format describing what post tags to filter post/item-level data by. E.g. {"conjunction":"any","values":[<tagId1>,<tagId2>],"untagged":false}
  • postText (optional): A configuration in JSON format describing what text to filter post/item-level data by. E.g. {"values":["keyword1", "keyword2"],"conjunction":"any"}

The following is an example for fetching the number of Page Likes for Facebook Pages

https://api.quintly.com/v0.9/qql?qqlQuery=SELECT%20profileId,%20time,%20fans%20FROM%20facebook&startTime=2014-01-01&endTime=2014-01-31&interval=weekly&profileIds=13,14

The response will be sent in JSON format. Here is a sample response for the example above: 

{
  "success":true,
  "data":[
    {"profileId":13,"time":"2013-12-30 00:00:00","fans":1372},
    {"profileId":14,"time":"2013-12-30 00:00:00","fans":218},
    {"profileId":13,"time":"2014-01-06 00:00:00","fans":1371},
    {"profileId":14,"time":"2014-01-06 00:00:00","fans":219},
    {"profileId":13,"time":"2014-01-13 00:00:00","fans":1371},
    {"profileId":14,"time":"2014-01-13 00:00:00","fans":219},
    {"profileId":13,"time":"2014-01-20 00:00:00","fans":1371},
    {"profileId":14,"time":"2014-01-20 00:00:00","fans":219},
    {"profileId":13,"time":"2014-01-27 00:00:00","fans":1372},
    {"profileId":14,"time":"2014-01-27 00:00:00","fans":219}
  ]
}

Authenticate profiles with Insights via quintly API

Please follow the documentation in our knowledge base

Fetching data source schemas

Please use the following endpoint for gathering the schema of all data sources. 

https://api.quintly.com/v0.9/data-sources

Error Handling

In case of errors, the HTTP status code returns either 404 for a non-existing resource or 500 for any other error. You can expect the following JSON response to be sent in the response's body. There is success set to false and errors and errors.reason holding more specific information about the error. In most cases errors.errorType will further return a unique identifier you can use to identify the specific error type. 

{
  "success": false,
  "errors": {
    "reason": "The underlying SQL query failed: no such table: instagramInsight",
    "errorType": "qqlMalformed"
  }
}

Rate limits

So far rate limits have been set very loose and you should not hit any limits at all.