Getting started

Welcome to the SE Ranking API! This guide will walk you through authenticating your account, making your first request, understanding our credit system, and more. Let’s get you up and running in minutes.

Authentication

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

https://api.seranking.com

1. Obtain Your API Key

First, you’ll need to generate a unique API key from your account dashboard.

1. Sign in to your SE Ranking account.

2. Navigate to Profile & Preferences → API Dashboard.

3. Click the Create API Key button.

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

2. Authenticate Your Requests

You have two methods to authenticate your requests. We strongly recommend using the Authorization header.

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 authenticated, you can make requests to any API endpoint.

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

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 System

API usage is managed through a credit system. Every successful API call (2xx status code) consumes a certain number of credits from your balance. Failed requests (4xx or 5xx errors) do not consume credits.

How Credits Are Billed

There are two cost models, depending on the endpoint:

• Cost per Request: A flat number of credits is charged for every successful API call.
• Cost per Record: Credits are charged for each record (e.g., a backlink, a keyword) returned in the response.

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

Endpoint cost matrix

* 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.

Forecasting Costs

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

Monitoring and replenishing your balance

• Check Your Balance: You can programmatically check your remaining credits by calling the GET /v1/account/subscription endpoint. This call is free.
• Insufficient Funds: If your balance reaches zero, any subsequent requests that consume credits will fail with an HTTP 400 Insufficient funds error.
• Replenishing Credits: To add more credits and ensure your workflow is never interrupted, you can:
  • Upgrade Your Plan: Instantly switch to a higher-tier plan.
  • Enable Overage: Contact support to allow your account to exceed its monthly credit limit. You will only be billed for the overage you use at the end of your billing cycle.

To upgrade your plan or enable overage, please contact our Support team at [email protected].

Pricing

Monthly subscription

The API credit plans are billed monthly.

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

If a request fails, the API will return an appropriate HTTP status code and a JSON body with an error description.

Error response example

{

  "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.