December 4, 2016

Frequently asked questions (FAQ)

We’ll update this section frequently. Before you contact the support please take a look if your issue is already covered by the answers provided on this page. If something remains unclear, please get in touch. Thanks a lot!



What is good for?
We’ve several use cases and much more in mind. It’s your choice. You’ve any freedom of how you use our service. It is good for a contextual video player, contextual advertising, content recommendation, tagging, enrich user profile data, affiliate cases and much more. Surprise us! We’re always interested in your use case(s). We would like to advertise your case here on our website! Just tell us!

How can I get an API-Key?
Just get in touch with us and request a personal API-Key via the web form. As an alternative, you write us an email to

Please keep in mind that we need your first and last name, a valid email address and some information about your company or your project. A URL or short description is fine.

Do I need a credit card to start the trial?
No. Just give us your real name, your email and in addition the name of your company – and we’re good to go.

What’s included in the trial?
Everything that is included in the JSON response – minus the dedicated onboarding support. We offer one response for all. Including website categorization and sentiment analysis too. No extra charge for these kind of information.

How long can I use the trial access?
As long as you want. We know it’s a technical product and you need time to a) implement and b) identify how you can use our service for your business or project.

What are the limits for the trial API access?
You’ve 10.000 API request per month for free. The access limit is 50 requests per second/burst 100 requests. If you need more, please get in touch with us and tell us what you try to achieve or test.

Is the API usable for any platform?
Because we provide a standard RESTful-API you can use the API for any web or mobile application where you need to determine contextual data out of websites or provided text.


Service, Website and Reporting

Do you have a User Interface (UI) to self-manage the API service?
This issue is on our roadmap. To be honest, it will take a while until the self-managed service will be available to the public. How long? Good question… next!

Can you limit the number of requests for an API-Key?
Yes, we can. If you want we’ll set a daily or monthly limit for a number of available API requests per API-Key. This means you’ve full control over your budget and aren’t risking a bad surprise by having a script running nuts on your application. By default, every API-Key has NO LIMITS, except the “Free API-Keys” (limited by default to 10.000 requests / per month).

Where can I get a current report of my API-Usage?
Until we’ve self-managing accounts you’ll receive a daily report with your API-Usage as PDF via E-Mail. In urgent cases, you can always get in contact with our Support.


Pricing, Payment & Plans

Why there is no usage plan and subscription available?
The platform is in an early stage. We currently give access to anyone who wants to test or use the service and selected partners. We’ve no plans, just volumes in a Pay-as-you-Go model.

Which subscription plans will be available?
Besides the Free API usage, we’ll offer no specific plans. We offer a volume-based pricing. Contact us for an individual pricing depending on your use case and expected API call volume.

What are the intended prices?
The pricing varies depending on the volume of requests and according to the additional information requested via the hyScore API. For any API call, we charge a technical CPM (1.000 API calls) of some EUR/USD cent. Because our self-service is not published yet, we’ll send you an individual offer based on the amount of your intended API call volume. Just get in touch with us.

Which payment methods are available yet?
Currently, we offer, depends on our financial risk assessment, to pay via bank transfer, SEPA Business to Business Direct Debit (only B2B) and PayPal. In some cases we only accept pre-payments. In the future, we want to offer other payment methods as well.


API response messages and possible issues

Please take a look at the API documentation for specific response and status messages!

My API-Key is not working, what’s wrong?
a) You’re API-Key is invalid. Please contact our support via email
b) Your trial limit has exceeded 10.000 API requests in the actual month or your API call quota has exceeded his limit (HTTP 429 – Too many requests, Limit exceeded).
c) Something with your payment processing might go wrong and your API-Key is temporarily deactivated. Please contact our support via email!

Is the API not working? I can’t connect to the API and get permanently a “Bad Gateway” error message.
If there’s a general problem with our service we’ll inform instantly on the website and on Twitter ( , otherwise please contact our support via email!

How can I provide feedback when the JSON response is looking weird. The result does not fit my expectation.
We’ve created a feedback form to streamline the feedback. Please provide the information here (Google form) and constantly working to improve the results. Thanks.

Sometimes there is a weird looking keyword in the results which have nothing to do with the contextual meaning.
This might be related to a couple of abbreviations in the text which is hard to classify. As you may know, an abbreviation can have more than one meaning. We’re continuously optimizing our hyScore algorithms to provide better results. Please send us these cases via our feedback form to streamline the feedback. Please provide the information here (Google form). Thanks.

Why the first request of a URL shows a response “No data yet” in the JSON response body?
The target URL was requested the first time and/or the source has some issues (e.g. invalid SSL certificate, etc.), or the article text / raw text is very long so that the analysis takes longer than 100ms. Depending on the load of the system the result is mostly available within the next or the next few requests. In a real-time environment, it isn’t that critical because you’ll get the results after another or a few requests. Depending on your use case it might make sense to wait a few seconds until the second request is made to get the results. We recommend waiting – if you do a one-time analysis of URLs e.g. like a classification/categorization of URLs – up to 90 seconds before the 2nd request to secure to get a full response.

Why is the category or IAB result “gx_retry”, “null” or “No channel returned” in the JSON response?
The target URL was requested the first time. To determine the website category can take a bit longer than determine keywords. Depending on the load of the system the result is mostly available within the next or the next few requests. Until the website category isn’t determined we show the message “gx_retry”. In some cases, you get a “null” or “No channel returned” in the JSON response. These two messages are deprecated and will be removed over time (self-cleaning process). Depending on your use case it might make sense to wait a few seconds until the second request is made to get a proper result for the same URL. It might be available in another few milliseconds or seconds. We recommend waiting – if you do a one-time analysis of URLs – up to 90 seconds before the 2nd request to secure to get a full response. For a specific URL bulk processing (one-time analysis) we will invent a specific endpoint soon.

What is the meaning of sentiment result “Could not get sentiment.”?
Currently, we support the sentiment analysis in German (DE) and English (EN) language only. We’ll extend this functionality to all supported languages step-by-step. For further information contact our support or take a look at this page.

Why there is from time to time no result at all?
Some publishers don’t allow to crawl their website and articles and set a restriction in the domains robots.txt – file. If a publisher has declined to crawl his website we’re not allowed to gather any contextual information from this specific domain/URL.

What kind of URL should I send to the API?
The API works the best with article and content website URLs (full URL). You should avoid sending IP-addresses, technical URLs (e.g. like dynamic AdServer URLs, CDN and storage URLs (like or any other URL which is not related to some content. No content – no contextual analysis. It is simple like that. You should filter up front which URLs you want to be analyzed by our API. This might help you to save costs too.



What is an API call/request?
An API call is a request to one of the APIs. To get some dataset from hyScore you would always make an API call (or several API calls, depending on your use case).

How do you count API calls?
Any request made to our API counts as 1 (“one”) API call/request, no matter how the result looks like. A “No data yet” response is a response too. We’ve seen the URL the first time and have to analyze it. If we’re not able to analyze a website because of its e.g. robots.txt settings it is also a valid response.

What is an SLA?
Standard SLA guarantees an uptime of 97.5% in year average and 250 ms response time (on API responses with payloads < 10 Kb).  If needed, this guarantee can be upgraded to a higher uptime with the help of extra servers, advanced failover scenarios, and increased monitoring. Get in touch. We’ll make an individual offer.

What is a dedicated infrastructure?
All our future self-service API are hosted on one shared infrastructure cluster, subject to shared API rate limits. Though unlikely, it is conceivable that the actions of some users may impact the experience of others, especially on the API layer. For the Enterprise tier, we’ll plan to offer in addition a dedicated infrastructure, which eliminates this risk and ensures a higher service level.

Last updated: 26th September 2017