1. Help Center
  2. Integrations & API

Frase API: Everything You Need to Know

Access powerful content data with Frase's API. Here's your complete guide.

In This Article

Authentication and Rate Limits

To use the Frase API, you must include your unique API key in every request.

In the top left corner of Frase, click your Name > Settings > API. You’ll find your API key and a graph showing current usage.

  • Authentication Format:
    Include the API key as a token field in your request header.
  • Rate Limits:
    • Free usage: 500 requests per hour. If you exceed your hourly limit, you’ll receive an error message.

    • Need more? Contact team@frase.io to explore paid options.

Key Endpoints

👉 Process SERP

Search Google, process the top 20 results, and aggregate insights for those pages. Optionally score your own URL against the results.

Endpoint:

https://api.frase.io/api/v1/process_serp

  • Request Type: POST
  • Header: token: YOUR_API_KEY

2 ways to process search results:

  1. Using Google Search API to Get Results. Frase will handle the search and result processing.
    Argument Description
    query The search query. string
    lang Language for search results. string (default: "en")
    country Country for search results. string (default: "us")
    count Number of search results. integer (default: 20)
    include_full_text Whether you want the response to include full text for each URL. boolean (default: false)
    user_url The URL you want to run topic scoring against. string (optional field)
    google_api_key Your Google API Key. You can find in your Google Console dashboard.
    google_search_engine_id Your Google Search Engine Id. How to create a Google search engine.
    Request body example
  2. Skip the Google search and provide your own URLs.
    1. If you already have a list of URLs with you, then you don't need to have Frase search Google.

    2. In this case, you can simplify your payload and directly send the list of URLs as "serp_urls".

      Argument Description
      serp_urls The list of URLs you want to process. Send as list of strings
      user_url The URL you want to run topic scoring against. string (optional field)
    3. Request body example
    4. If successful, the response will include the following fields:
      Field Description
      items List of processed URLs. See below detailed information about the Items object.
      cluster_info List of topic clusters, where each cluster has "cluster_entities" and "label"
      aggregate_metrics Average word count, average headers, and average external links per item. This will also include avg. topic score if "user_url" was part of the payload.
      user_url_metrics Topic score, word count, header count, and external link count for the "user_url". This field is only returned if "user_url" was part of the payload.
    5. The Items object includes a list, with one object per processed URL. 

      Each processed URL includes the following data:

      Field Description
      title title tag
      url canonical URL
      description description tag
      date date published tag
      author author tag
      links list of hyperlinks
      images list of image URLs
      language language tag
      clean_text full clean text
      html clean html for content
      word_count clean text word count
      assets list of sections with headings and text
      questions list of question headings
      entities list of topics sorted by count
      statistics list of sentences containing stats

👉 Process URL

Extract content from a single page and get structured text.

Endpoint:

https://api.frase.io/api/v1/process_url

  • Request Type: POST
  • Header: token: YOUR_API_KEY
  • Arguments:
Argument Description
url the URL you want to process. string
include_full_text include full text as part of the response. boolean (default: true)
  • Request body example:
  • Response:

    If successful, the response will include the following fields:

    Field Description
    title title tag
    url canonical URL
    description description tag
    date date published tag
    author author tag
    links list of hyperlinks
    images list of image URLs
    videos list of video URLs
    language language tag
    clean_text full clean text
    html clean html for content
    word_count clean text word count
    assets list of sections with headings and text
    questions list of question headings
    entities list of topics sorted by count
    statistics list of sentences containing stats

👉 Get Document

Returns information for a specific Frase document. Requires the document ID and access permission.

Endpoint:

https://api.frase.io/api/v1/get_document_id

  • Request Type: POST
  • Header: token: YOUR_API_KEY
  • Arguments:
    Argument Description
    doc_id the ID of your document. string

  • Request body example:

  • Response

    If successful, the response will include the following fields:

    Field Description
    doc_owner user ID. integer
    user_name user email. integer
    date_created date document was created
    last_edited date document was last edited
    title document title
    query target search query for document
    html document full html

👉 Get Documents by User

Fetch all documents created by a user in your organization by email.

Endpoint:

https://api.frase.io/api/v1/get_documents_email

  • Request Type: POST
  • Header: token: YOUR_API_KEY
  • Arguments:
Argument Description
email the user email. string
 
  • Request Body Example:

  • Response:

    The response is a list of document objects, where each object includes the following information:

    Field Description
    doc_owner user ID. integer
    user_name user email. integer
    date_created date document was created
    last_edited date document was last edited
    title document title
    query target search query for document
    html document full html
 

Pricing

If you're on a paid Frase content plan, the Frase API can be used with up to 500 URLs/month available for free.

The number of credits consumed depends on the API endpoint you are using:

    Endpoint Credits Used
    Content API Free (endpoint for retrieving Frase documents)
    Process URL 1 per URL
    Process SERP 20 URLs per successfully processed SERP (each query processes 20 URLs since "count" is 20 by default) 

    Reach out to team@frase.io if you'd like to learn more about paid API plans.

    Terms and Conditions

    Customers with access to Frase API must comply to the Terms & Conditions explained in this article. Please carefully review the stipulations below before using our API services:

    • You are not allowed to white-label our data without our approval.
    • If you show our data to third party, you are asked to follow attribution requirements. It may be done in different ways. If you are not sure, contact us at team@frase.io. Frase reserves the right to decide which kind of attribution is sufficient in your case and therefore it may vary from case to case.
    • Access to API may be suspended or terminated anytime and for any reason.
    • If your access to Frase API is cancelled due to breach of our terms, you are not entitled to get a refund of any kind.
    • Frase reserves the right to discontinue providing service anytime and for any reason.

    Do note that we will continue to update this page as more API specifications and functionalities are added.

    Have questions about the Frase API? Reach out anytime at team@frase.io.