Frase API: Everything You Need to Know
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
tokenfield 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 [email protected] 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:
Using Google Search API to Get Results. Frase will handle the search and result processing.
Request body example
- Skip the Google search and provide your own URLs.
- If you already have a list of URLs with you, then you don't need to have Frase search Google.
- In this case, you can simplify your payload and directly send the list of URLs as "serp_urls".
Request body example
- If successful, the response will include the following fields:
The Items object includes a list, with one object per processed URL.
Each processed URL includes the following data:
| 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. |
| 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) |
| 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. |
| 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:
Request body example:
Response
If successful, the response will include the following fields:
| Argument | Description |
| doc_id | the ID of your document. string |
| 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 |
|---|---|
| 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.
These are our API paid plans:
$40 - 10,000 urls (~500 serps)
$100 - 25,000 urls (~1,250 serps)
$200 - 50,000 urls (~2,500 serps)
Enterprise / custom price above 50k URLs.
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 [email protected] 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 [email protected]. 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 [email protected].