API Documentation | LinksTest

Create Test (Async)

URL: https://linkstest.com/api/tests
Method: POST
Auth: Api-Key header

API Access: Your account must be on an API-enabled plan to use this endpoint.

Request Parameters

Parameter	Type	Description	Required
url	string	URL of the test	Yes
country	string	2 letter ISO country code	Yes
device	string	"Android", "iOS", "Mac", "Windows"	Yes
version	string	Optional OS version hint	No
city	string	Optional city override	No

Request Format

{
  "test": {
    "url": "http://example.com/test",
    "country": "us",
    "device": "Android"
  }
}

Response Format (Queued)

{
  "status": "pending",
  "test_id": "uuid",
  "credits_remaining": 987
}

Check Test Status

URL: https://linkstest.com/api/tests/{test_id}
Method: GET
Auth: Api-Key header

Status Response (Success)

{
  "status": "success",
  "test_id": "uuid",
  "result": {
    "result": "success",
    "test_id": "uuid",
    "data": {
      "init": {
        "url": "http://example.com/test",
        "os": "Android",
        "country": "us",
        "version": "",
        "city": ""
      },
      "hops": [
        {
          "from": "https://example.com/initial",
          "to": "https://example.com/redirect1",
          "status": 302
        }
      ]
    }
  },
  "credits_remaining": 987
}

Code Examples

PHP Example

$url = 'https://linkstest.com/api/tests';
$apiKey = 'your_api_key_here'; // Replace with actual API key

$data = [
    'test' => [
        'url' => 'http://example.com/test',
        'country' => 'us',
        'device' => 'Android'
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Api-Key: ' . $apiKey
]);

$response = curl_exec($ch);

if ($response === false) {
    echo 'Curl error: ' . curl_error($ch);
}

curl_close($ch);
$result = json_decode($response, true);
echo $response;

// Poll for result
if (!empty($result['test_id'])) {
    $statusUrl = 'https://linkstest.com/api/tests/' . $result['test_id'];
    $attempts = 0;
    while ($attempts < 10) {
        sleep(2);
        $ch = curl_init($statusUrl);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Api-Key: ' . $apiKey
        ]);
        $statusResponse = curl_exec($ch);
        curl_close($ch);
        echo $statusResponse;
        $attempts++;
    }
}

Python Example

import requests
import json
import time

url = 'https://linkstest.com/api/tests'
api_key = 'your_api_key_here'  # Replace with actual API key

data = {
    'test': {
        'url': 'http://example.com/test',
        'country': 'us',
        'device': 'Android'
    }
}

headers = {
    'Content-Type': 'application/json',
    'Api-Key': api_key
}

try:
    response = requests.post(url, json=data, headers=headers)
    response.raise_for_status()
    result = response.json()
    print(json.dumps(result, indent=2))

    test_id = result.get('test_id')
    if test_id:
        status_url = f'https://linkstest.com/api/tests/{test_id}'
        for _ in range(10):
            time.sleep(2)
            status_resp = requests.get(status_url, headers={'Api-Key': api_key})
            print(status_resp.text)
except requests.exceptions.RequestException as e:
    print(f'Error: {e}')

Node.js Example

const fetch = require('node-fetch');

const url = 'https://linkstest.com/api/tests';
const apiKey = 'your_api_key_here';  // Replace with actual API key

const data = {
    test: {
        url: 'http://example.com/test',
        country: 'us',
        device: 'Android'
    }
};

const options = {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Api-Key': apiKey
    },
    body: JSON.stringify(data)
};

fetch(url, options)
    .then(response => {
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return response.json();
    })
    .then(async result => {
        console.log(JSON.stringify(result, null, 2));
        if (result.test_id) {
            const statusUrl = `https://linkstest.com/api/tests/${result.test_id}`;
            for (let i = 0; i < 10; i++) {
                await new Promise(resolve => setTimeout(resolve, 2000));
                const statusRes = await fetch(statusUrl, {
                    headers: { 'Api-Key': apiKey }
                });
                const statusBody = await statusRes.text();
                console.log(statusBody);
            }
        }
    })
    .catch(error => {
        console.error('Error:', error);
    });

💡 Tip: Remember to replace 'your_api_key_here' with your actual API key from your LinksTest account settings.

Common Errors

Error	Status	Description
Invalid or missing API Key	401	Authentication failed
Insufficient credits	401	You do not have enough credits to perform this request
API access not enabled	403	Your current plan does not include API access
Invalid data format	400	Invalid or poorly formatted data
Missing test object	400	'test' is required and must be an array
Missing required fields	400	Every test must contain 'url', 'country', and 'device'
Test not found	404	Invalid test_id when checking status
Invalid URL	400	The provided URL is not valid
Invalid country	400	Country is not valid
Invalid device	400	Device is not valid
Method not allowed	405	Invalid HTTP method used
Endpoint not found	404	The requested endpoint does not exist