Search jobs (GET)

Search jobs using natural language via query parameters. Results are sorted by publish_time descending, then by relevance score.

Authorization

apiKeyAuth

x-api-key<token>

API key authentication. Pass the key via the x-api-key header.

In: header

Query Parameters

q*string

Natural language search query. Supports keywords or full sentences.

Length1 <= length

city?string

City name filter (exact match, case-sensitive).

country?string

Country code filter (exact match on country_code field).

Match^[A-Z]{2}$

since?string

Earliest publish time filter. Only returns jobs published after this time. Supports "YYYY-MM-DD" (auto-completed to "YYYY-MM-DD 00:00:00") and "YYYY-MM-DD HH:MM:SS" (full format).

Match^\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?$

until?string

Latest publish time filter (V4 F-5). Only returns jobs published before this time. Supports "YYYY-MM-DD" (auto-completed to "YYYY-MM-DD 00:00:00") and "YYYY-MM-DD HH:MM:SS" (full format).

Match^\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?$

top_k?integer

Number of results to return. Values outside the valid range are clamped automatically.

Default20

Range1 <= value <= 100

offset?integer

Pagination offset (V4 F-4). 0-based index of the first result to return. Use with top_k for pagination: offset=0&top_k=10 → page 1, offset=10&top_k=10 → page 2.

Default0

Range0 <= value

detail?string

Controls response detail level. "summary" (default) returns compact results without job descriptions. "full" includes the complete job_description text.

Default"summary"

Value in"summary" | "full"

source?string

Data source filter (V4 F-3). Filters results to only return jobs from the specified source. Must be one of the valid values; invalid values return 400.

Value in"indeed" | "linkedin"

Response Body

`application/json`

curl -X GET "https://ufdqwbefaj.execute-api.us-east-1.amazonaws.com/v1/search?q=Python+backend+developer+in+New+York&city=New+York&country=US&since=2025-01-01&until=2025-12-31&top_k=10&offset=0&detail=summary&source=linkedin"

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "total": 3,
  "search_time_ms": 234,
  "results": [
    {
      "score": 0.92,
      "job_title": "Senior Python Backend Developer",
      "city": "New York",
      "company_name": "Acme Corp",
      "publish_time": "2025-03-15 10:30:00",
      "base_salary": "125000.0-160000.0 USD/YEAR",
      "job_url": "https://example.com/jobs/12345",
      "job_tags": [
        "python",
        "backend",
        "senior"
      ],
      "data_source": "linkedin",
      "seniority_level": "Mid-Senior level",
      "employment_type": "Full-time"
    },
    {
      "score": 0.85,
      "job_title": "Python Software Engineer",
      "city": "New York",
      "company_name": "Tech Inc",
      "publish_time": "2025-03-10 08:00:00",
      "base_salary": "90000.0-120000.0 USD/YEAR",
      "job_url": "https://example.com/jobs/12346",
      "job_tags": [
        "python",
        "software-engineer"
      ],
      "data_source": "indeed"
    }
  ]
}

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": "q is required",
  "error_code": "MISSING_QUERY"
}

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": "Invalid API key",
  "error_code": "AUTH_INVALID_KEY"
}

{
  "error": "Rate limit exceeded",
  "retry_after": 12
}

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": "Internal server error",
  "error_code": "INTERNAL_ERROR"
}

Search jobs (GET)

Authorization

Query Parameters

Response Body

200application/json

400application/json

403application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`