Run a slow service as a background job
curl --request POST \
--url https://api.retriever.run/v1/services/jobs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"service": "getEmail",
"input": {}
}
'import requests
url = "https://api.retriever.run/v1/services/jobs"
payload = {
"service": "getEmail",
"input": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({service: 'getEmail', input: {}})
};
fetch('https://api.retriever.run/v1/services/jobs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.retriever.run/v1/services/jobs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'service' => 'getEmail',
'input' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.retriever.run/v1/services/jobs"
payload := strings.NewReader("{\n \"service\": \"getEmail\",\n \"input\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.retriever.run/v1/services/jobs")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"service\": \"getEmail\",\n \"input\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.retriever.run/v1/services/jobs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"service\": \"getEmail\",\n \"input\": {}\n}"
response = http.request(request)
puts response.read_body{}{
"ok": true,
"job_id": "svcjob_9f2c4b1e8a7d6c5f",
"service": "<string>",
"status": "queued",
"poll_url": "<string>",
"created_at": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_authenticated",
"message": "A valid API key is required."
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded. Retry later."
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}Services
Run a slow service as a background job
For services whose provider takes minutes to respond: getEmail,
getPhoneNumber, webResearch, getLinkedInUserComments,
getLinkedInUserReactions. Retriever responds immediately with an id,
does the work, and keeps the result until you fetch it, even if your
client disconnected in the meantime.
Any other service is rejected with service_not_async: call it directly
on POST /services/{serviceName}; it responds in a few seconds.
Idempotency-Key is recommended. Replaying the same key with the same
body returns the first job and 200 instead of 202, so a retried
request never pays for two executions.
POST
/
v1
/
services
/
jobs
Run a slow service as a background job
curl --request POST \
--url https://api.retriever.run/v1/services/jobs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"service": "getEmail",
"input": {}
}
'import requests
url = "https://api.retriever.run/v1/services/jobs"
payload = {
"service": "getEmail",
"input": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({service: 'getEmail', input: {}})
};
fetch('https://api.retriever.run/v1/services/jobs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.retriever.run/v1/services/jobs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'service' => 'getEmail',
'input' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.retriever.run/v1/services/jobs"
payload := strings.NewReader("{\n \"service\": \"getEmail\",\n \"input\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.retriever.run/v1/services/jobs")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"service\": \"getEmail\",\n \"input\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.retriever.run/v1/services/jobs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"service\": \"getEmail\",\n \"input\": {}\n}"
response = http.request(request)
puts response.read_body{}{
"ok": true,
"job_id": "svcjob_9f2c4b1e8a7d6c5f",
"service": "<string>",
"status": "queued",
"poll_url": "<string>",
"created_at": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_authenticated",
"message": "A valid API key is required."
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded. Retry later."
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}Authorizations
API key ret_live_… created in Settings → API keys.
Headers
Body
application/json
Response
Replay of an already-used Idempotency-Key: the existing job.
The response is of type object.