GET /bulk/jobs API

GET/bulk/jobs

• Bulk

List recent bulk jobs submitted by the caller.

Parameters

Parameters

Name	In	Type	Required	Description
status	query	string	No	Filter bulk jobs by their current status.
after	query	string	No	Return jobs created after the supplied ISO-8601 timestamp.
limit	query	integer	No	Maximum number of items to return.
cursor	query	string	No	Cursor returned by a previous `/bulk/jobs` response.

• statusqueryOptional
  Typestring

  Filter bulk jobs by their current status.

• afterqueryOptional
  Typestring

  Return jobs created after the supplied ISO-8601 timestamp.

• limitqueryOptional
  Typeinteger

  Maximum number of items to return.

• cursorqueryOptional
  Typestring

  Cursor returned by a previous `/bulk/jobs` response.

Sample responses

Sample responses

• 200 Success — List of jobs ordered from newest to oldest.

  application/json → BulkJobList

  Paginated list of bulk jobs.

  {
    "cursor": "eyJwYWdlIjowfQ==",
    "jobs": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "status": "processing",
        "submitted_at": "2024-03-18T12:40:00Z",
        "started_at": "2024-03-18T12:41:05Z",
        "input": {
          "transport": "https",
          "url": "https://files.example.com/batches/sprint-42.csv"
        },
        "callback": {
          "url": "https://app.example.com/webhooks/geocoding",
          "secret": "whsec_example_secret_01",
          "signature_header": "X-Geobridge-Signature"
        },
        "options": {
          "output_format": "geojson",
          "truncate_at": 5
        },
        "metadata": {
          "batch_id": "sprint-42"
        },
        "statistics": {
          "total_records": 1000,
          "processed_records": 640,
          "successful_records": 638,
          "failed_records": 2,
          "last_record_id": "rec-640"
        }
      },
      {
        "id": "223e4567-e89b-12d3-a456-426614174000",
        "status": "succeeded",
        "submitted_at": "2024-03-17T09:15:00Z",
        "started_at": "2024-03-17T09:16:12Z",
        "completed_at": "2024-03-17T09:18:54Z",
        "input": {
          "transport": "s3",
          "url": "s3://geobridge-jobs/2024/03/17/customer.csv.gz",
          "compression": "gzip"
        },
        "callback": {
          "url": "https://app.example.com/webhooks/geocoding",
          "secret": "whsec_example_secret_02",
          "signature_header": "X-Geobridge-Signature"
        },
        "options": {
          "output_format": "ndjson"
        },
        "statistics": {
          "total_records": 5000,
          "processed_records": 5000,
          "successful_records": 4990,
          "failed_records": 10
        }
      }
    ],
    "next_cursor": "eyJwYWdlIjoxfQ=="
  }

• 401 Client error — Missing or invalid API key.

  application/problem+json → Problem

  API key rejected when listing jobs.

  {
    "type": "https://docs.geobridge.io/problems/unauthorized",
    "title": "Unauthorized",
    "status": 401,
    "detail": "API key is missing or invalid."
  }

• 429 Client error — Too many requests. Retry after the rate limit resets.

  application/problem+json → Problem

  Listing polled too frequently.

  {
    "type": "https://docs.geobridge.io/problems/too-many-requests",
    "title": "Too Many Requests",
    "status": 429,
    "detail": "Job list may be requested at most once per second."
  }

• 500 Server error — Unexpected server error.

  application/problem+json → Problem

  Internal error while enumerating jobs.

  {
    "type": "https://docs.geobridge.io/problems/internal-error",
    "title": "Internal Server Error",
    "status": 500,
    "detail": "Failed to fetch job list from storage backend."
  }

Code samples

Code samples

200 OK

cURL

# 200 OK — Lists processing jobs with pagination.
curl -s -G 'https://api-na.geobridge.io/v1/bulk/jobs' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'status=processing' \
  --data-urlencode 'limit=25' \
  --data-urlencode 'cursor=eyJwYWdlIjowfQ=='

Node.js

// 200 OK — Lists processing jobs with pagination.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  status: 'processing',
  limit: '25',
  cursor: 'eyJwYWdlIjowfQ=='
});
const requestUrl = `https://api-na.geobridge.io/v1/bulk/jobs?${params.toString()}`;
const response = await fetch(requestUrl, {
  method: 'GET',
  headers: {
    'Accept': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

Python

# 200 OK — Lists processing jobs with pagination.
import requests

url = 'https://api-na.geobridge.io/v1/bulk/jobs'
params = {
  "status": "processing",
  "limit": "25",
  "cursor": "eyJwYWdlIjowfQ=="
}
headers = {
  "Accept": "application/json",
  "X-API-Key": "YOUR_API_KEY"
}
payload = None
response = requests.get(url, params=params, headers=headers, timeout=10)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

Go

// 200 OK — Lists processing jobs with pagination.
package main

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

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/bulk/jobs")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("status", "processing")
  q.Set("limit", "25")
  q.Set("cursor", "eyJwYWdlIjowfQ==")
  u.RawQuery = q.Encode()
  req, err := http.NewRequest(http.MethodGet, u.String(), nil)
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

Java

// 200 OK — Lists processing jobs with pagination.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/bulk/jobs?status=processing&limit=25&cursor=eyJwYWdlIjowfQ=="))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_API_KEY")
        .timeout(Duration.ofSeconds(10))
        .GET()
        .build();

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

C#

// 200 OK — Lists processing jobs with pagination.
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(HttpMethod.Get, "https://api-na.geobridge.io/v1/bulk/jobs?status=processing&limit=25&cursor=eyJwYWdlIjowfQ==");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");

        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

401 Unauthorized

cURL

# 401 Unauthorized — Using an invalid API key triggers authentication failure when listing jobs.
# Uses an invalid API key to trigger authentication errors.
curl -s -G 'https://api-na.geobridge.io/v1/bulk/jobs' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: INVALID_API_KEY' \
  --data-urlencode 'status=queued'

Node.js

// 401 Unauthorized — Using an invalid API key triggers authentication failure when listing jobs.
// Purposely uses an invalid API key value.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "status": "queued"
});
const requestUrl = `https://api-na.geobridge.io/v1/bulk/jobs` + `?${params.toString()}`;
const response = await fetch(requestUrl, {
  method: 'GET',
  headers: {
    'X-API-Key': 'INVALID_API_KEY'
  },
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

Python

# 401 Unauthorized — Using an invalid API key triggers authentication failure when listing jobs.
import requests

url = 'https://api-na.geobridge.io/v1/bulk/jobs'
params = {
  "status": "queued"
}
headers = {
  "X-API-Key": "INVALID_API_KEY"
}
payload = None
response = requests.get(url, params=params, headers=headers, timeout=10)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

Go

// 401 Unauthorized — Using an invalid API key triggers authentication failure when listing jobs.
package main

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

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/bulk/jobs")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("status", "queued")
  u.RawQuery = q.Encode()
  req, err := http.NewRequest(http.MethodGet, u.String(), nil)
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "INVALID_API_KEY")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

Java

// 401 Unauthorized — Using an invalid API key triggers authentication failure when listing jobs.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/bulk/jobs?status=queued"))
        .header("Accept", "application/json")
        .header("X-API-Key", "INVALID_API_KEY")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .timeout(Duration.ofSeconds(10))
        .build();

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

C#

// 401 Unauthorized — Using an invalid API key triggers authentication failure when listing jobs.
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api-na.geobridge.io/v1/bulk/jobs?status=queued");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "INVALID_API_KEY");
        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

429 Too Many Requests

cURL

# 429 Too Many Requests — Polling the bulk job list too aggressively returns a rate limit error.
curl -s -G 'https://api-na.geobridge.io/v1/bulk/jobs' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'status=processing' \
  --data-urlencode 'limit=25' \
  --data-urlencode 'cursor=eyJwYWdlIjoxfQ=='

Node.js

// 429 Too Many Requests — Polling the bulk job list too aggressively returns a rate limit error.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  status: 'processing',
  limit: '25',
  cursor: 'eyJwYWdlIjoxfQ=='
});
const requestUrl = `https://api-na.geobridge.io/v1/bulk/jobs?${params.toString()}`;
const response = await fetch(requestUrl, {
  method: 'GET',
  headers: {
    'Accept': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

Python

# 429 Too Many Requests — Polling the bulk job list too aggressively returns a rate limit error.
import requests

url = 'https://api-na.geobridge.io/v1/bulk/jobs'
params = {
  "status": "processing",
  "limit": "25",
  "cursor": "eyJwYWdlIjoxfQ=="
}
headers = {
  "Accept": "application/json",
  "X-API-Key": "YOUR_API_KEY"
}
payload = None
response = requests.get(url, params=params, headers=headers, timeout=10)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

Go

// 429 Too Many Requests — Polling the bulk job list too aggressively returns a rate limit error.
package main

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

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/bulk/jobs")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("status", "processing")
  q.Set("limit", "25")
  q.Set("cursor", "eyJwYWdlIjoxfQ==")
  u.RawQuery = q.Encode()
  req, err := http.NewRequest(http.MethodGet, u.String(), nil)
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

Java

// 429 Too Many Requests — Polling the bulk job list too aggressively returns a rate limit error.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/bulk/jobs?status=processing&limit=25&cursor=eyJwYWdlIjoxfQ=="))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_API_KEY")
        .timeout(Duration.ofSeconds(10))
        .GET()
        .build();

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

C#

// 429 Too Many Requests — Polling the bulk job list too aggressively returns a rate limit error.
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(HttpMethod.Get, "https://api-na.geobridge.io/v1/bulk/jobs?status=processing&limit=25&cursor=eyJwYWdlIjoxfQ==");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");

        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

500 Internal Server Error

cURL

# 500 Internal Server Error — Demonstrates error handling when the job listing endpoint fails.
curl -s -G 'https://api-na.geobridge.io/v1/bulk/jobs' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'status=succeeded' \
  --data-urlencode 'limit=10'

Node.js

// 500 Internal Server Error — Demonstrates error handling when the job listing endpoint fails.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "status": "succeeded",
  "limit": "10"
});
const requestUrl = `https://api-na.geobridge.io/v1/bulk/jobs` + `?${params.toString()}`;
const response = await fetch(requestUrl, {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  },
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

Python

# 500 Internal Server Error — Demonstrates error handling when the job listing endpoint fails.
import requests

url = 'https://api-na.geobridge.io/v1/bulk/jobs'
params = {
  "status": "succeeded",
  "limit": "10"
}
headers = {
  "X-API-Key": "YOUR_API_KEY"
}
payload = None
response = requests.get(url, params=params, headers=headers, timeout=10)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

Go

// 500 Internal Server Error — Demonstrates error handling when the job listing endpoint fails.
package main

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

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/bulk/jobs")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("status", "succeeded")
  q.Set("limit", "10")
  u.RawQuery = q.Encode()
  req, err := http.NewRequest(http.MethodGet, u.String(), nil)
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

Java

// 500 Internal Server Error — Demonstrates error handling when the job listing endpoint fails.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/bulk/jobs?status=succeeded&limit=10"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_API_KEY")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .timeout(Duration.ofSeconds(10))
        .build();

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

C#

// 500 Internal Server Error — Demonstrates error handling when the job listing endpoint fails.
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api-na.geobridge.io/v1/bulk/jobs?status=succeeded&limit=10");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");
        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

Try it live

Try it live

Save your API key once and reuse it across endpoints. Configure the request below and send it directly from the docs.

API key

Clear

Stored locally in your browser. Removing it clears access for this device.

Serverhttps://api.geobridge.io/v1

Query parameters

status

Filter bulk jobs by their current status.

after

Return jobs created after the supplied ISO-8601 timestamp.

limit

Maximum number of items to return.

cursor

Cursor returned by a previous `/bulk/jobs` response.

Send request Reset

Configure the request and select “Send request” to preview the response.

—