Best Practices

Use specific filters

For Company Jobs, provide a LinkedIn URL and use the documented filter names:

{
  "company_linkedin_url": "https://www.linkedin.com/company/stripe/",
  "jobs_locations": [{"country": "United States"}],
  "department": ["Engineering"],
  "seniority_level": ["Mid Level"]
}

industry is supported by Jobs Search, not Company Jobs. Company Jobs ignores that field. Department and seniority filters are arrays, even for a single value.

Use idempotency keys for search retries

Send the optional Idempotency-Key header with Jobs Search and Company Jobs requests, including their historical endpoints. Generate a key once per logical request and keep it with the request body so you can reuse both if a timeout or connection failure leaves the outcome unknown.

Reuse the same key, endpoint, and request body when retrying that request.
Generate a new key for a new search or a changed request, including each new page of results: changing search_after changes the request.
Use use_v1_ followed by 1–121 ASCII letters, digits, underscores, or hyphens. For example, "use_v1_" + uuid4().hex in Python produces a valid key.
A malformed key returns 400. A key reused with changed request intent or an expired billing period returns 409. Inspect the error before deciding to start a new request with a new key; do not automatically replace the key on every retry.

from uuid import uuid4

# Create once for this request; retain it for any retries.
idempotency_key = "use_v1_" + uuid4().hex
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Idempotency-Key": idempotency_key,
}

Paginate large result sets

Pass data.search_after back unchanged while keeping your search filters fixed. Use a new idempotency key for each page, and retain that page’s key if you retry it:

import os
from uuid import uuid4

import requests

search_after = None
all_jobs = []

while True:
    # Retain this key and request body if this page needs to be retried.
    idempotency_key = "use_v1_" + uuid4().hex
    response = requests.post(
        "https://api.sentrion.ai/api/v1/company-jobs/search",
        headers={
            "Authorization": f"Bearer {os.environ['SENTRION_API_KEY']}",
            "Idempotency-Key": idempotency_key,
        },
        json={
            "company_linkedin_url": "https://www.linkedin.com/company/google/",
            "limit": 100,
            "search_after": search_after,
        },
        timeout=120,
    )
    response.raise_for_status()
    payload = response.json()
    if not payload["success"]:
        raise RuntimeError(payload.get("error") or "Search failed")
    all_jobs.extend(payload["data"]["jobs"])
    search_after = payload["data"]["search_after"]
    if not search_after:
        break

Monitor credits

Search responses include data.credits_used and data.credits_remaining. Use GET /api/v1/credits/balance for a fresh balance without running a search. Reference endpoints are free and accept active keys with zero remaining credits.

Log request IDs

Every HTTP response, including errors, includes an X-Request-ID header with a server-generated UUID for that HTTP attempt. Add this value to your application logs, especially when logging errors, so you can trace a failed request. It is separate from the billing operation key in Idempotency-Key.

Choose your date window

Use published_after and published_before. Current v1 searches cover the latest six months. Historical searches cover postings back to 2020 and are included on every plan. Set explicit dates to select your historical window. Use limit between 10 and 100 and pass data.search_after back unchanged to retrieve subsequent pages.

Rate Limiting

Respect rate limits to avoid throttling.
Implement exponential backoff for retries, reusing the same idempotency key and request body for each attempt.
Cache results when possible to reduce unnecessary API calls.

Overview

Endpoints

Historical (Since 2020)

Billing

Use specific filters

Use idempotency keys for search retries

Paginate large result sets

Monitor credits

Log request IDs

Choose your date window

Rate Limiting

​Use specific filters

​Use idempotency keys for search retries

​Paginate large result sets

​Monitor credits

​Log request IDs

​Choose your date window

​Rate Limiting

Use specific filters

Use idempotency keys for search retries

Paginate large result sets

Monitor credits

Log request IDs

Choose your date window

Rate Limiting