Getting started

Guide to getting started with the Analytics API

Overview

The Analytics API enables you to access Analytics data from your account.

GraphQL

The Analytics API is based on the GraphQL query language. This allows you to create any query for data that is supported by the API and customize those queries to only receive the data you need. Additionally, strong typing and schema definition makes the API easy to use and understand. In your account, when you access the Analytics API, the interface provides developer data documentation as well as a query schema. Data from this API is returned in a JSON format.

Authentication

Our API uses Basic Authentication, requiring an API username and API key for access. Ensure that both credentials are included in your request headers to authenticate successfully. They are available in the “Account”, “API Configuration” section of the dashboard.

Using the Analytics API

The API can be accessed via the Creatable Dashboard.

The API explorer is unique to your account, if you notice the API URL in the explorer, that is specific for you.

The left panel is your working area, where you can construct, test and troubleshoot queries to the API.

The right panel is your results area. This is where you will see data responses or error messages based on your query from the left panel.

To execute a query, paste or write it into the left panel, then hit the PLAY button in between both panels.

Here’s an example query to retrieve social posts:

{
  social_report(start: "2023-01-01", end: "2025-06-12", page: 1, per_page: 20) {
    total,
    items {
      social_platform
      social_post_id
       post_type
       post_date
       social_post_text
       social_post_link
       creator_first_name
       creator_last_name
       creator_id
       employee_id
       store
       region
       creator_tier
       likes
       shares
       views
       comments
       max_reach
       max_views
       saves
       impressions
       engagements
       engagement_rate
       boosted
       emv
    }
  }
}

The tabs at the top allow you to work with many queries at the same time without having to lose any work.

For convenience, you can click “COPY CURL” and this will allow you to paste a command into a standard unix/linux terminal to execute the query to our API using a generic CURL command.

API Access

The Analytics API is an authenticated API meant to be used by our clients to get Analytics data for internal purposes. The API URL you see in the explorer is unique to your account. If for any reason you need to invalidate this URL and generate a new one, please contact our support Analytics.

Note: this will disable any API calls being made to the former URL.

Limits

The Team API is rate limited, meaning you can make up to 10 requests per second before the rate limiting will be enforced. When this happens, you will receive a 429 HTTP code.

The best practice for working with this API is to throttle the requests being made until the API responds with a normal 200 HTTP code and queue/retry the requests that were not successful.

Additionally, this API has a maximum result set of 100 items per page.

API response times vary depending on the amount of data being requested and the period being requested. Simple requests can take only ~30ms while more complex requests can maximally be up to 30 seconds depending on the amount of data being requested.

API Endpoint

Here is an example of the API endpoint:

https://app.creatable.io/v2/api/analytics/brand/graphql/v1/kYNsGq374mq4ZZAi9x94HzquRvQ3SBmG/playground.html

You can see there the URL is comprised of:

The API hostname test.creatable.io
The version /v2 subfolder indicating the API version you are currently using
The /api/analytics/brand subfolder
The account specific hash /, which represents your account
The /graphql endpoint identifier

Error handling

The API explorer has built-in syntax validation, so if there is ever a problem with your query, the errors will be highlighted for you and provide some hints on where the problem is.

The following are examples of common errors that might occur and their resulting error messages:

Invalid date format

Request

{
  metrics(start_date: "202501-01", end_date: "2025-02-01") {
    site {
      video_visits_count
    }
  }
}

Response

{
    "errors": [
        {
            "message": "Query does not pass validation. Violations:\n\nExpected type 'Date!', found '\"202501-01\"'. Date value expected in format YYYY-MM-DD (line 2, column 23):\n  metrics(start_date: \"202501-01\", end_date: \"2025-02-01\")",
            "locations": []
        }
    ]
}

Missing required argument

Request

{
  metrics(start_date: "2025-01-01") {
    site {
      video_visits_count
    }
  }
}

Response

{
  "error": {
    "errors": [
      {
        "message": "Query does not pass validation. Violations:\n\nField 'metrics' argument 'end_date' of type 'Date!' is required but not provided. (line 2, column 3):\n  metrics(start_date: \"2025-01-01\") {\n  ^",
        "locations": []
      }
    ]
  }
}

Invalid query syntax

Request

{
  metrics(start_date: "2025-01-01" end_date: "2025-02-01") {
    site {
     
    }
  }
}

Response

{
  "errors": [
    {
      "message": "Syntax error while parsing GraphQL query. Invalid input \"\"2025-02-01\") {\\n    site {\\n      \\n    }\", expected Value, Argument, Directives or SelectionSet (line 2, column 47):\n  metrics(start_date: \"2025-01-01\", end_date: \"2025-02-01\") {\n                                              ^",
      "locations": [
        {
          "line": 2,
          "column": 47
        }
      ]
    }
  ]
}

If you have any additional problems using the Analytics API, please reach out to our support team and we'll be happy to help.