# Overview

> How the Easyparser Real-Time API works: endpoint, authentication, the shared response envelope, timeouts, rate limits and errors.

Source: https://docs.easyparser.com/real-time-integration/overview

The Real-Time API returns parsed Amazon data as JSON in the response to a single HTTP GET request. You choose what to fetch with the `operation` parameter, and every operation returns the same response envelope.

## How it works

The Real-Time API is synchronous:

1. You send a GET request with your `api_key`, the `operation` and its parameters.
2. Easyparser fetches the Amazon page, extracts the data and structures it as JSON.
3. The same HTTP response carries the result.

There are no job IDs, polling or webhooks. Use the Real-Time API when you need data immediately, for example in a live application, a user-triggered lookup or a price check. To process thousands of inputs asynchronously with webhook delivery, use the [Bulk API](/bulk-integration/overview).

## Endpoint and authentication

```http
GET https://realtime.easyparser.com/v1/request
```

Every parameter goes in the query string, including your API key in `api_key`. The Real-Time API does not accept the key in an `Authorization: Bearer` header.

You find your API key in the web app under **Account > Plan** at https://app.easyparser.com/account/plan. New accounts get 100 free credits per month, with no credit card required. For a visual walkthrough, see [Getting Started](/getting-started).

> **WARNING:** Regenerating your API key in the web app deletes the current key immediately and cannot be undone. Update every integration that uses the old key.

Example request for the Detail operation (`DETAIL`):

**cURL**

```bash
curl --get "https://realtime.easyparser.com/v1/request" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "platform=AMZ" \
  --data-urlencode "operation=DETAIL" \
  --data-urlencode "domain=.com" \
  --data-urlencode "asin=B0CJB6V2L5" \
  --data-urlencode "language=en_US" \
  --data-urlencode "currency=usd"
```

**Python**

```python
import requests

params = {
    "api_key": "YOUR_API_KEY",
    "platform": "AMZ",
    "operation": "DETAIL",
    "domain": ".com",
    "asin": "B0CJB6V2L5",
    "language": "en_US",
    "currency": "usd",
}

response = requests.get("https://realtime.easyparser.com/v1/request", params=params)
print(response.json())
```

**Node.js**

```javascript
const params = new URLSearchParams({
  api_key: "YOUR_API_KEY",
  platform: "AMZ",
  operation: "DETAIL",
  domain: ".com",
  asin: "B0CJB6V2L5",
  language: "en_US",
  currency: "usd",
});

const response = await fetch(`https://realtime.easyparser.com/v1/request?${params}`);
const data = await response.json();
console.log(data);
```

**HTTP**

```http
GET /v1/request?api_key=YOUR_API_KEY&platform=AMZ&operation=DETAIL&domain=.com&asin=B0CJB6V2L5&language=en_US&currency=usd HTTP/1.1
Host: realtime.easyparser.com
```

**PHP**

```php
<?php
$params = [
    'api_key' => 'YOUR_API_KEY',
    'platform' => 'AMZ',
    'operation' => 'DETAIL',
    'domain' => '.com',
    'asin' => 'B0CJB6V2L5',
    'language' => 'en_US',
    'currency' => 'usd',
];

$url = 'https://realtime.easyparser.com/v1/request?' . http_build_query($params);
$response = file_get_contents($url);
$data = json_decode($response, true);
print_r($data);
```

**Go**

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
)

func main() {
	params := url.Values{}
	params.Add("api_key", "YOUR_API_KEY")
	params.Add("platform", "AMZ")
	params.Add("operation", "DETAIL")
	params.Add("domain", ".com")
	params.Add("asin", "B0CJB6V2L5")
	params.Add("language", "en_US")
	params.Add("currency", "usd")

	resp, err := http.Get("https://realtime.easyparser.com/v1/request?" + params.Encode())
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

**C#**

```csharp
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;

var parameters = new Dictionary<string, string>
{
    ["api_key"] = "YOUR_API_KEY",
    ["platform"] = "AMZ",
    ["operation"] = "DETAIL",
    ["domain"] = ".com",
    ["asin"] = "B0CJB6V2L5",
    ["language"] = "en_US",
    ["currency"] = "usd",
};

var query = string.Join("&", parameters.Select(p =>
    $"{Uri.EscapeDataString(p.Key)}={Uri.EscapeDataString(p.Value)}"));

using var client = new HttpClient();
var response = await client.GetStringAsync($"https://realtime.easyparser.com/v1/request?{query}");
Console.WriteLine(response);
```

**Java**

```java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.stream.Collectors;

public class EasyparserRequest {
    public static void main(String[] args) throws Exception {
        Map<String, String> params = new LinkedHashMap<>();
        params.put("api_key", "YOUR_API_KEY");
        params.put("platform", "AMZ");
        params.put("operation", "DETAIL");
        params.put("domain", ".com");
        params.put("asin", "B0CJB6V2L5");
        params.put("language", "en_US");
        params.put("currency", "usd");

        String query = params.entrySet().stream()
            .map(e -> URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8) + "="
                + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&"));

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://realtime.easyparser.com/v1/request?" + query))
            .GET()
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
```

The parameters every request needs (`api_key`, `platform`, `operation`, `domain`) and the shared optional ones are described in [Common Request Fields](/real-time-integration/common-required-request-fields).

## Operations

| Operation | Code | Reference |
|---|---|---|
| Detail | `DETAIL` | [Request](/real-time-integration/detail/request), [Response](/real-time-integration/detail/response) |
| Offer | `OFFER` | [Request](/real-time-integration/offer/request), [Response](/real-time-integration/offer/response) |
| Sales Analysis and History | `SALES_ANALYSIS_HISTORY` | [Request](/real-time-integration/sales-analysis-and-history/request), [Response](/real-time-integration/sales-analysis-and-history/response) |
| Best Sellers Rank | `BEST_SELLERS_RANK` | [Request](/real-time-integration/best-sellers-rank/request), [Response](/real-time-integration/best-sellers-rank/response) |
| Package Dimension | `PACKAGE_DIMENSION` | [Request](/real-time-integration/package-dimension/request), [Response](/real-time-integration/package-dimension/response) |
| Search | `SEARCH` | [Request](/real-time-integration/search/request), [Response](/real-time-integration/search/response) |
| Product Lookup | `PRODUCT_LOOKUP` | [Request](/real-time-integration/product-lookup/request), [Response](/real-time-integration/product-lookup/response) |
| Seller Profile | `SELLER_PROFILE` | [Request](/real-time-integration/seller-profile/request), [Response](/real-time-integration/seller-profile/response) |
| Seller Products | `SELLER_PRODUCTS` | [Request](/real-time-integration/seller-products/request), [Response](/real-time-integration/seller-products/response) |
| Seller Feedback | `SELLER_FEEDBACK` | [Request](/real-time-integration/seller-feedback/request), [Response](/real-time-integration/seller-feedback/response) |
| Similar Products | `SIMILAR_PRODUCTS` | [Request](/real-time-integration/similar-products/request), [Response](/real-time-integration/similar-products/response) |

Credit costs differ by operation and options. See [Credit Consumption](/essentials/credit-consumption).

## Response envelope

Every Real-Time API response is a JSON object with four top-level objects:

```
{
  request_info        status, errors, credits and the address used
  request_parameters  echo of the parameters you sent
  request_metadata    timing (and pagination details for some operations)
  result              the operation payload
}
```

Always check `request_info.success` and `request_info.error_details`, even when the HTTP status is `200`.

### `request_info`

| Field | Type | Description |
|---|---|---|
| `id` | string | Unique request ID (UUID). Log it to trace a request. |
| `success` | boolean | `true` when the data was extracted successfully. |
| `status_code` | integer | Status of the Amazon page fetch, similar to an HTTP status code. `0` when the page could not be fetched or parsed. |
| `error_details` | array | Errors for this request. Empty on success. |
| `error_details[].error_code` | integer | Error code. |
| `error_details[].message` | string | Error message. |
| `credits_used` | integer | Credits your account has used in the current billing cycle. |
| `credit_used_this_request` | integer | Credits charged for this request. |
| `credits_remaining` | integer | Credits left in the current billing cycle after this request. |
| `credits_reset_at` | string | Date and time (ISO 8601) when your credits reset. |
| `address` | object | Delivery address used for the request. When you send no address, this is the marketplace default. |
| `address.zipCode` | array | Zip or postal code. A two-part code such as `N0E,1Y0` comes back as two entries. |
| `address.city` | string or null | City, when set. |
| `address.district` | string or null | District, when set. |
| `address.country_code` | string or null | ISO 3166 alpha-2 country code, when set. |

### `request_parameters`

An echo of the parameters Easyparser applied to the request, so you can confirm what was processed.

| Field | Type | Description |
|---|---|---|
| `type` | string | The operation code you sent in `operation`, for example `SEARCH`. |
| `output` | string | Response format. Always `json`. |
| `language` | string | Language applied to the request, for example `en_US`. |
| `operation_version` | integer | Operation version applied, for versioned operations. See [Operation Versioning](/essentials/operation-versioning). |

The object also echoes the operation parameters you sent, such as `asin`, `keyword` or `history_range`. Some numeric inputs come back as strings (for example `history_range` and `similar_limit`). Compare values as strings or convert them before you compare.

### `request_metadata`

| Field | Type | Description |
|---|---|---|
| `created_at` | string | Date and time (ISO 8601) when the request was received. |
| `processed_at` | string | Date and time (ISO 8601) when processing finished. |
| `total_time_taken` | number | Processing time in seconds. |

Paginated operations can add pagination fields, either to `request_metadata` (for example `end_of_pagination` and `pages[]` in the sample below) or to `result`. Each operation's response page shows where its pagination data appears.

### `result`

`result` holds the operation payload. Its structure depends on the operation (for example `result.detail` for `DETAIL` and `result.search_results` for `SEARCH`) and is documented on each operation's response page. On failure, `result` is an empty object.

#### Sample envelope (SEARCH, .com, result omitted)

```json
{
  "request_info": {
    "id": "a12b3456-caed-491b-8a91-d5ff517d63dc",
    "success": true,
    "status_code": 200,
    "error_details": [],
    "credits_used": 759040,
    "credit_used_this_request": 1,
    "credits_remaining": 759050,
    "credits_reset_at": "2035-01-30T00:00:00.000Z",
    "address": {
      "city": null,
      "district": null,
      "country_code": null,
      "zipCode": [
        "19805"
      ]
    }
  },
  "request_parameters": {
    "output": "json",
    "language": "en_US",
    "include_html": false,
    "keyword": "winter",
    "type": "SEARCH"
  },
  "request_metadata": {
    "created_at": "2025-05-27T13:15:00.496Z",
    "processed_at": "2025-05-27T13:15:03.561Z",
    "total_time_taken": 3.065,
    "end_of_pagination": 7,
    "pages": [
      {
        "current_page": 1,
        "current_page_link": "/s?k=winter&language=en_US&xpid=GUHHVwhvUwDys&qid=1748351701",
        "result_count": 60,
        "next_page_link": "/s?k=winter&page=2&language=en_US&xpid=GUHHVwhvUwDys&qid=1748351701&ref=sr_pg_1",
        "not_match": [
          "related_searches"
        ],
        "ms": 2790
      }
    ]
  }
}
```

## Timeouts and rate limits

| Limit | Value |
|---|---|
| Server-side timeout | 15 seconds |
| Server-side timeout with inline address fields (`zip_code`, `city`, `district`, `country_code`) | 45 seconds |
| Pages per request (paginated operations) | 5 |
| Rate limit | Credits per minute, set by your plan (see [Plan limits](/essentials/credit-consumption#plan-limits)) |

- A request that exceeds the timeout fails with an error. Sending `address_id` does not change the timeout.
- Set your HTTP client timeout to at least 60 seconds so that it does not cut off requests the server is still processing.
- Your per-minute limit is returned by the [Account API](/account/account-api) in `minutely_real_time_credit_limit`. A request above the limit returns HTTP `429` (`Too Many Requests`). Wait and retry with backoff.

## Errors and status codes

| HTTP status | Meaning |
|---|---|
| `200` | Request processed. Still check `request_info.success` and `request_info.error_details`. |
| `400` | Missing or invalid parameter. |
| `401` | Missing or invalid API key. |
| `402` | Your monthly credits are used up, or your subscription has ended. |
| `403` | Request not permitted. |
| `404` | Not found, for example an unknown ASIN on `SIMILAR_PRODUCTS`. |
| `429` | Per-minute rate limit exceeded. |
| `500` | Server or upstream error. Retry later. |
| `504` | Upstream failure, documented for `SIMILAR_PRODUCTS`. Not charged. |

Error bodies do not all have the same shape. Depending on the error, the body can contain `request_info` with `success: false`, a `message`, or only an `error` field (a string or an object). Read the HTTP status first, then any of these fields.

Common message codes:

| Code | Message |
|---|---|
| `MSG0014` | You do not have enough quota |
| `MSG0017` | No active package found |
| `MSG0023` | Invalid API Key. Please verify your API key is valid |
| `MSG1006` | Too Many Requests |
| `MSG1009`, `MSG1013` | Address not found |
| `MSG1010` | Maximum page count must be more than minimum page count |
| `MSG1011` | Invalid url |
| `MSG1012` | Invalid Platform |
| `MSG1015` | Invalid language for domain |
| `MSG1016` | There is no such address or it has been deleted before. |
| `MSG1019` | Invalid Search Term |

> **INFO:** Failed requests are not charged. One exception: a `SIMILAR_PRODUCTS` request for an unknown ASIN returns `404` and costs 1 credit. See [Credit Consumption](/essentials/credit-consumption).

Failed requests are listed on the Errors page of the web app (https://app.easyparser.com/errors) with the request ID, operation and error code. Filter the list, for example by operation, and open **Payload** to see the parameters and the error message of a request.

![Animation: on the Errors page, filter by the OFFER operation and open the log details of a failed request with error MSG1015](https://docs.easyparser.com/media/animations/docs-real-time-overview-errors.jpg)

*Animation: on the Errors page, filter by the OFFER operation and open the log details of a failed request with error MSG1015* ([MP4](https://docs.easyparser.com/media/animations/docs-real-time-overview-errors.mp4))

## Testing in the Playground

The API Playground at https://app.easyparser.com/playground lets you build a request in a form, send it and inspect the JSON response before you write code. It shows the credit cost of the request, your remaining credits and code samples in several languages.

Playground requests are real API calls and use your credits. If you do not have an account yet, sign up at https://app.easyparser.com/signup to get 100 free credits per month.

## Related

- [Common Request Fields](/real-time-integration/common-required-request-fields)
- [Credit Consumption](/essentials/credit-consumption)
- [Supported Marketplaces](/essentials/supported-marketplaces)
- [Address Management](/essentials/address-management)
- [Bulk API overview](/bulk-integration/overview)