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 contextual video views, contextual advertising, content recommendation, tagging, enrich user profile data, affiliate cases and much more. Surprise us! We’re always interested in your use cases. 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 alternative you write us a 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 actually – minus the dedicated on-boarding support. It might be that with our final subscription plans (we’ll announce asap) may not include the feature/information “website category” by default – its optional. Why? Because this specific information is provided by a partner and might increase the technical CPM a bit. For demonstration purposes we thought its some added value to get the category of the website together with the contextual keywords within the same JSON result.

How long I can use the trial access?
As long as you want. We know its 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’ve 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 amount of requests for an API-Key?
Yes, we can. If you want we’ll set a daily or monthly limit for the amount of available API requests per API-Key. This means you’ve full control over your budget and are’nt 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 are no plans and subscription available yet?
The platform is in 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?
Beside 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 request 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 requests we charge a technical CPM (1.000 API calls) of some EUR/USD cent. Because our subscription is not published yet, we’ll send you an individual offer based on the amount of your intended API request volume. Talk to 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 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) You’re trial limit has exceed 10.000 API requests in the actual month.
c) Something with your payment processing might went wrong and your API-Key is temporarily deactivated. Please contact our support via email!

The API is 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 weird looking keyword in the results which has nothing to do with the contextual meaning.
This might be related to a couple of abbreviations in the text which are 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.

Why the category or iab result is “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 to wait – if you do a one time analysis of URLs – up to 90 seconds before the 2nd request to secure to get a full response.

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 is an API call?
An API call is a request to one of the APIs. To get some data set 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.

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: 3rd July 2017