Getting started

Creating an API Key

1. Sign in to your SE Ranking account.

2. Navigate to Profile & Preferences → API Dashboard.

3. Click the Create API Key button and then copy the generated key value.

4. Copy the generated key value. Treat this key like a password and keep it secure.

Note: You can issue a single key per account.

Authentication

All requests to the Data API must be authenticated. The base URL for all endpoints is:

https://api.seranking.com

You have two primary methods to authenticate your API requests.

Method 1: Authorization Header (Recommended)

Include an Authorization header in your request, with the value Token YOUR_API_KEY.

You can test your key by fetching your subscription details. A 200 OK response confirms that your key is working correctly.

curl -X GET 'https://api.seranking.com/v1/account/subscription' \

  -H 'Authorization: Token YOUR_API_KEY'

Method 2: Query Parameter

Alternatively, you can pass the key as a URL query parameter named apikey.

curl -X GET 'https://api.seranking.com/v1/account/subscription?apikey=YOUR_API_KEY'

Making a request

Once you have successfully authenticated, you can make requests to any API endpoint. Requests follow the same structure as the authentication examples above.

• GET requests can include parameters in the URL’s query string.
• POST requests send data in a JSON body and must include the Content-Type: application/json header.

Example POST Request

Here is an example of a more complex POST request to the /backlinks/summary endpoint. Notice how the authentication header remains the same.

curl -X POST 'https://api.seranking.com/v1/backlinks/summary' \

  -H 'Authorization: Token YOUR_API_KEY' \

  -H 'Content-Type: application/json' \

  -d '{

    "target": "seranking.com",

    "mode": "host"

  }'

Postman Collection

We offer a Postman collection to help you get started without writing any code. Postman is a free application that makes it easy to explore and test APIs.

Prerequisites

• Postman
• SE Ranking Account

Getting Started

To get started fork the collection from SE Ranking’s public workspace within Postman.

Enter a name for your fork and select the workspace where it will be created:

You can also fork the environment template from the SE Ranking Developers Workspace:

Set your API key

To run requests you’ll need to supply your secret API key and set it as an environment variable within your workspace.

To set any environment variable, create a new environment within Postman:

Add your secret key as a variable to the environment and save:

Set the environment to active:

Now within the collection set it to use the environment you just created:

If your environment is set up correctly, you should see your secret key value if you mouse over the secret_key_data variable in the Token field:

Be sure to save the collection after you’ve set the key:

Make a test call

You should be ready now to make a test call. An easy first call is to create a customer:

Since this is a test, no parameters updates are required. You can hit the Send button to run this request:

If your environment is set up you’ll get a summary object back as the response to the call:

Add parameters to the call by clicking the Params tab, where you’ll see a list of available parameters. Select and populate the ones you want to use. Here’s an example of updating a target parameter:

You’ll see the updated target in the response:

Glossary

Regional Database Codes

Use one of the following codes as the value of the source parameter when you want a request to target a specific regional keyword database.

The list mirrors the ISO 3166-1 alpha-2 country codes except for the special alias worldwide (an aggregated global dataset).

Note: If a code you send is not supported, the API returns 400 Invalid source.

SERP Features

Use one of the following codes as the value of the serp_features parameter when you want a request to target keywords with specific SERP features.

The list includes all supported SERP feature identifiers.

Rate Limits

Request-rate limit

• If the threshold is exceeded the API responds with HTTP 429 “Too Many Requests” and the body explains that the call-rate limit has been reached .
• The window is rolling, so waiting 100–200 ms before retrying is usually enough. We recommend an exponential back-off strategy with jitter to avoid synchronized retry storms.
• Asynchronous endpoints such as /backlinks/export only count the initial task-creation request against your rate; polling /export/status is subject to the same 10 rps ceiling.

Custom Rate Limits

If your application requires a higher throughput, the standard rate limit can be customized. To discuss a plan that fits your specific needs, please contact our team.

• Book a meeting
• Email us

Credits quota

Credit quotas govern how many requests you can make in total. Every successful request (2xx status code) consumes a certain number of API credits from your subscription balance.

Monitoring Your Balance

A key part of maintaining a robust integration is actively monitoring your API credit balance. Refer to the complete specification for the endpoint to implement this check:

• GET /v1/account/subscription

Credit Costs

You are billed in credits. The number of credits depends on the endpoint and how much data you process.

There are two cost models:

• Cost per Request
  • You pay a flat number of credits for every successful 2xx call.
• Cost per Record
  • You pay for each record in a successful 2xx response.
  • For backlinks endpoints, a record is an object like a backlink, refdomain, referring IP, indexed page, or history item.

Charges only apply to successful 2xx responses. 4xx and 5xx do not consume credits.

Endpoint cost matrix

• 2xx Request Cost applies once per successful call.
• 2xx Response Record Cost applies per record returned in the 2xx response.

* SERP classic/results_advanced charges 100 credits a single time per task when fetching advanced results. Subsequent reads of the same task do not reapply this cost.

Special notes

• Backlinks family uses Cost per Record. Multiply the per-record cost by the number of records returned.
• Site Audit per page cost depends on the crawl type: standard is 2 per page, advanced is 20 per page.
• Export status endpoints are free.
• Account subscription lookups are free.

Forecasting costs before you run

• List the calls in your workflow.
• Multiply each call by its credit cost from the table.
• Sum the costs for all calls in the workflow.
• Compare the projected total with your credits_left (obtained via the /v1/account/subscription endpoint ).

Example: You need backlink summaries for 250 domains and a full export for one of them.

• /backlinks/summary batched in groups of 100 → 3 calls × 10 credits = 30 credits
• /backlinks/export task creation → 1 call × 1000 credits = 1000 credits
• /backlinks/export/status polled twice → 2 calls × 1 credits = 2 credits
  

Total forecast = 1032 credits. Ensure at least that many remain or top-up first.

Insufficient Funds

Should your credits_left balance reach zero, any subsequent API requests that ordinarily consume credits will result in an HTTP 400 Insufficient funds error. Access to the API service will be temporarily suspended until your credits balance has been replenished.

Replenishing Credits

Ensure your workflow is never interrupted by a lack of credits. We offer two flexible options to keep your Data API calls running smoothly:

• Upgrade Your Plan. Instantly switch to a higher-tier plan at any time.
• Enable Overage. Activate plan-specific overage to continue making API calls even after your monthly credit balance is depleted. You only pay for what you exceed, billed at the end of your cycle. Overage is disabled by default.

To make changes to your plan, please contact our Support team at [email protected].

API — Monthly subscription

Our standalone API plans are billed monthly.

API — Annual subscription

Commit to an annual plan and save 20% vs. paying monthly. Your full yearly credit allowance is available upfront at the start of the subscription.

How to upgrade in one minute

• Ping Support via chat with your email and the plan you want overage on.
• They will enable it for the current and consecutive cycles.

Enabling overage

• Ping Support via chat with your email and the plan you want overage on.
• They will enable it for the current and consecutive cycles.
• When your balance hits zero, calls continue and extra credits accrue at the overage rate shown in the table. You can disable the feature at any time.

Error Handling

Error envelope

{

  "error_description": "Unsupported 'output' format. Supported 'output' formats are 'json' (default) and 'xml'."

}

Canonical error codes

If a request to the API fails, the HTTP response will return an error, including the error code and a detailed description of the error in the response’s body.

Below are the details of common errors you may experience while working with the SE Ranking Backlinks API.