Oxylabs Documentation


Realtime is a synchronous integration method. This means that upon sending your job submission request, you will have to keep the connection open until we successfully finish your job or return an error.
The TTL of Realtime connections is 150 seconds. There may be rare cases where your connection times out before you receive a response from us, for example, if our system is under heavier-than-usual load or the job you submitted was extremely hard to complete.


POST https://realtime.oxylabs.io/v1/queries


When submitting a job via Realtime, you have to send your job parameters inside a JSON payload. Please see the example below for more details:
curl --user "USERNAME:PASSWORD" \
'https://realtime.oxylabs.io/v1/queries' \
-H "Content-Type: application/json" \
-d '{"source": "universal", "url": "https://example.com", "geo_location": "United States"}'
import requests
from pprint import pprint
# Structure payload.
payload = {
"source": "universal", # Source you choose e.g. "universal"
"url": "https://example.com", # Check the docs of the specific source you're using to see if you should use "url" or "query"
"geo_location": "United States", # Some sources accept post codes and/or coordinates
#"render" : "html", # Uncomment you want to render JavaScript on the page
#"parse" : true, # Check what sources support parsed data
# Get response.
response = requests.request(
auth=('YOUR_USERNAME', 'YOUR_PASSWORD'), #Your credentials go here
# Instead of response with job status and results url, this will return the
# JSON response with results.
$params = array(
'source' => 'universal', //Source you choose e.g. "universal"
'url' => 'https://example.com', // Check the docs of the specific source you're using to see if you should use "url" or "query"
'geo_location' => 'United States', //Some sources accept zip-code or coordinates
//'render' : 'html', // Uncomment you want to render JavaScript within the page
//'parse' : TRUE, // Check what sources support parsed data
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://realtime.oxylabs.io/v1/queries");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, "YOUR_USERNAME" . ":" . "YOUR_PASSWORD"); //Your credentials go here
$headers = array();
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$result = curl_exec($ch);
echo $result;
if (curl_errno($ch)) {
echo 'Error:' . curl_error($ch);
curl_close ($ch);
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;
namespace OxyApi
class Program
static async Task Main()
const string Username = "YOUR_USERNAME";
const string Password = "YOUR_PASSWORD";
var parameters = new Dictionary<string, string>()
{ "source", "universal" },
{ "url", "https://example.com" },
{ "geo_location", "United States" },
var client = new HttpClient();
Uri baseUri = new Uri("https://realtime.oxylabs.io");
client.BaseAddress = baseUri;
var requestMessage = new HttpRequestMessage(HttpMethod.Post, "/v1/queries");
requestMessage.Content = JsonContent.Create(parameters);
var authenticationString = $"{Username}:{Password}";
var base64EncodedAuthenticationString = Convert.ToBase64String(System.Text.ASCIIEncoding.UTF8.GetBytes(authenticationString));
requestMessage.Headers.Add("Authorization", "Basic " + base64EncodedAuthenticationString);
var response = await client.SendAsync(requestMessage);
var contents = await response.Content.ReadAsStringAsync();
package main
import (
func main() {
const Username = "YOUR_USERNAME"
const Password = "YOUR_PASSWORD"
payload := map[string]string{
"source": "universal",
"url": "https://example.com",
"geo_location": "United States",
jsonValue, _ := json.Marshal(payload)
client := &http.Client{}
request, _ := http.NewRequest("POST",
request.SetBasicAuth(Username, Password)
response, _ := client.Do(request)
responseText, _ := ioutil.ReadAll(response.Body)
package org.example;
import okhttp3.*;
import org.json.JSONObject;
public class Main implements Runnable {
private static final String AUTHORIZATION_HEADER = "Authorization";
public static final String USERNAME = "YOUR_USERNAME";
public static final String PASSWORD = "YOUR_PASSWORD";
public void run() {
JSONObject jsonObject = new JSONObject();
jsonObject.put("source", "universal");
jsonObject.put("url", "https://example.com");
jsonObject.put("geo_location", "United States");
Authenticator authenticator = (route, response) -> {
String credential = Credentials.basic(USERNAME, PASSWORD);
return response
.header(AUTHORIZATION_HEADER, credential)
var client = new OkHttpClient.Builder()
var mediaType = MediaType.parse("application/json; charset=utf-8");
var body = RequestBody.create(jsonObject.toString(), mediaType);
var request = new Request.Builder()
try (var response = client.newCall(request).execute()) {
assert response.body() != null;
} catch (Exception exception) {
System.out.println("Error: " + exception.getMessage());
public static void main(String[] args) {
new Thread(new Main()).start();
import fetch from 'node-fetch';
const username = 'YOUR_USERNAME';
const password = 'YOUR_PASSWORD';
const body = {
source: 'universal',
url: 'https://example.com',
geo_location: 'United States'
const response = await fetch('https://realtime.oxylabs.io/v1/queries', {
method: 'post',
body: JSON.stringify(body),
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64'),
console.log(await response.json());


An example of a response that you can expect to get from Realtime:
"results": [
"content": "<html>
"created_at": "2019-10-01 00:00:01",
"updated_at": "2019-10-01 00:00:15",
"id": null,
"page": 1,
"url": "https://www.example.com/",
"job_id": "12345678900987654321",
"status_code": 200