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.

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

Unit quota

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

Monitoring Your Balance

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

• GET /v1/account/subscription

Unit Costs

The number of units consumed depends on the endpoint and the number of items processed. There are two primary cost models:

Cost per Record

For backlinks endpoints, you are charged for each object (e.g., backlinks, refdomain) in your request.

Cost per Request

For other endpoints, you are charged a flat rate for each successful API call.

Forecasting costs before you run

• List the calls in your workflow.
• Multiply each call by its unit cost from the table.
• Sum the costs for all calls in the workflow.
• Compare the projected total with your units_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 units = 30 units
• /backlinks/export task creation → 1 call × 1000 units = 1000 units
• /backlinks/export/status polled twice → 2 calls × 1 unit = 2 units
  

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

Insufficient Funds

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

Replenishing Units

Running out of credits should never stall your workflow. Two levers keep you moving:

• Switch to a higher plan – activates instantly, unused credits roll over to the higher cap.
• Enable plan-specific overage – pay only for what you exceed, billed at the end of the cycle. Overage is off by default; ask Support to flip the switch for your key.

*Pay-yearly prices already include a 20% discount vs paying monthly.

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.