Get a job

GET https://api.linkskipper.app/v1/jobs/{job_id} · Any valid API key.

When POST /v1/resolve returns 202, it gives you a job_id. Poll this endpoint to track the resolve until it finishes. The job belongs to the API key that created it — fetching another key’s job returns not_found (404).

Request

Path parameters

string

required

The job UUID returned by POST /v1/resolve. Must be a valid UUID; a malformed id returns not_found (404).

Headers

string

required

Bearer sk_live_…. See Authentication.

Response

string

The job UUID.

string

One of queued, running, done, failed, invalid. See Lifecycle.

string

Present only when status is done. The resolved destination URL.

string

Present only when status is done. The provider that owned the link (e.g. ouo).

string

Present only when status is done. "standard" or "premium".

string

Present only when status is failed or invalid. resolve_failed for a failed job, unsupported_link for an invalid one.

number

Credits spent on this job. The successful cost when done; 0 when failed / invalid.

number | null

Your current credit balance.

Examples

curl https://api.linkskipper.app/v1/jobs/9b1d7c0e-2f3a-4b5c-8d6e-1a2b3c4d5e6f \
  -H "Authorization: Bearer sk_live_XXXXXXXXXXXXXXXXXXXXXXXX"

const job = await client.getJob("9b1d7c0e-2f3a-4b5c-8d6e-1a2b3c4d5e6f");

switch (job.status) {
  case "done":
    console.log(job.targetUrl);
    break;
  case "queued":
  case "running":
    // keep polling
    break;
  default:
    console.error("failed:", job.error);
}

<?php

use LinkSkipper\Enum\JobStatus;

$job = $client->getJob("9b1d7c0e-2f3a-4b5c-8d6e-1a2b3c4d5e6f");

if ($job->status === JobStatus::Done) {
    echo $job->targetUrl, PHP_EOL;
} elseif ($job->status->isTerminal()) {
    fwrite(STDERR, "failed: " . $job->error . PHP_EOL);
}

Responses by status

done
queued / running
failed
invalid

{
  "job_id": "9b1d7c0e-2f3a-4b5c-8d6e-1a2b3c4d5e6f",
  "status": "done",
  "target_url": "https://example.com/final",
  "provider": "ouo",
  "tier": "standard",
  "credits_charged": 1,
  "balance": 248
}

{
  "job_id": "9b1d7c0e-2f3a-4b5c-8d6e-1a2b3c4d5e6f",
  "status": "running",
  "balance": 249
}

{
  "job_id": "9b1d7c0e-2f3a-4b5c-8d6e-1a2b3c4d5e6f",
  "status": "failed",
  "error": "resolve_failed",
  "credits_charged": 0,
  "balance": 249
}

{
  "job_id": "9b1d7c0e-2f3a-4b5c-8d6e-1a2b3c4d5e6f",
  "status": "invalid",
  "error": "unsupported_link",
  "credits_charged": 0,
  "balance": 249
}

Job lifecycle

A job moves through these states. queued, running are non-terminal — keep polling. done, failed, invalid are terminal — stop polling.

Status	Terminal	Meaning
`queued`	no	Accepted and waiting for a worker.
`running`	no	A worker is resolving the link right now.
`done`	yes	Resolved. `target_url`, `provider`, `tier`, `credits_charged` set.
`failed`	yes	The resolver couldn’t resolve it. `error` is `resolve_failed`.
`invalid`	yes	The link wasn’t a supported/resolvable target. `error` is `unsupported_link`.

Polling guidance

Poll on a short, fixed interval — 1.5–2 seconds is a good default. Standard links typically resolve in seconds; premium (exe.io) links are best-effort and slower.
Stop as soon as status is done, failed, or invalid.
Set an overall deadline (e.g. 60–120s) so a stuck job doesn’t poll forever.
Reads count against your per-minute rate limit like any request — don’t poll tighter than ~1s.
Prefer webhooks for high volume so you don’t poll at all.

The SDKs implement this loop for you. resolveAndWait (JS / PHP) submits the resolve, polls until terminal, and returns the resolved link — throwing JobFailedError / JobFailedException on failed / invalid and TimeoutError / TimeoutException if the deadline passes. See JavaScript and PHP.

Get started

API

Reference

SDKs

Request

Path parameters

Headers

Response

Examples

Responses by status

Job lifecycle

Polling guidance

​Request

​Path parameters

​Headers

​Response

​Examples

​Responses by status

​Job lifecycle

​Polling guidance

Request

Path parameters

Headers

Response

Examples

Responses by status

Job lifecycle

Polling guidance