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

• Key Endpoints

  • Process SERP

  • Process URL

  • Get Document

  • Get Documents by User

• Pricing

• Terms and Conditions

   

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:

• 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:

• Request Type: POST
• Header: token: YOUR_API_KEY
• Arguments:

👉 Get Document

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

Endpoint:

• 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

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

Endpoint:

• Request Type: POST
• Header: token: YOUR_API_KEY
• Arguments:

• 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