Jobs

Docs

Jobs

Fetch Twitter Jobs and get comprehensive information about job listings, companies, positions, and application details.

Overview

The Jobs endpoints provide access to Twitter's job listings platform, allowing you to retrieve job postings, company information, position details, and application data. These endpoints are essential for building job search applications, recruitment tools, or career platforms integrated with Twitter.

Key Features

Job Listings: Access comprehensive job postings with full details
Company Information: Get detailed company profiles and information
Position Details: Retrieve complete position descriptions and requirements
Search & Filter: Search jobs by keywords, location, company, and more
Application Data: Access application information and requirements
Real-Time Updates: Get the most current job listings available

Authentication

All endpoints require authentication via the X-API-KEY header:

X-API-KEY: YOUR_API_KEY

For detailed authentication information, see our Authentication Guide.

Endpoints

Get Job by ID

Retrieves detailed information about a specific job posting, including position details, company information, requirements, and application instructions.

Endpoint: GET /job/{job_id}

Path Parameters

Name	Type	Required	Description
`job_id`	string	Yes	The unique job ID

Request Examples

curl --request GET \
  --url 'https://<direct.gateway>/job/1234567890123456789' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

const response = await fetch('https://<direct.gateway>/job/1234567890123456789', {
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});
const job = await response.json();

Python:

import requests
 
response = requests.get(
    'https://<direct.gateway>/job/1234567890123456789',
    headers={'X-API-KEY': 'YOUR_API_KEY'}
)
job = response.json()

Response Example

{
  "id": "1234567890123456789",
  "title": "Senior Software Engineer",
  "description": "We are looking for an experienced software engineer...",
  "company": {
    "id": "987654321",
    "name": "Tech Company Inc.",
    "username": "techcompany",
    "verified": true,
    "logo_url": "https://pbs.twimg.com/profile_images/...",
    "website": "https://techcompany.com",
    "description": "Leading technology company",
    "location": "San Francisco, CA",
    "employee_count": "1000-5000"
  },
  "location": {
    "type": "remote",
    "city": "San Francisco",
    "state": "CA",
    "country": "United States",
    "remote_allowed": true
  },
  "employment_type": "full-time",
  "salary": {
    "min": 120000,
    "max": 180000,
    "currency": "USD",
    "period": "yearly"
  },
  "requirements": {
    "experience_level": "senior",
    "education": "Bachelor's degree or equivalent",
    "skills": ["JavaScript", "React", "Node.js", "TypeScript"],
    "years_experience": 5
  },
  "posted_at": "2024-10-01T10:00:00.000Z",
  "application_url": "https://techcompany.com/careers/apply/123",
  "application_deadline": "2024-11-01T23:59:59.000Z",
  "views": 1523,
  "applications": 87
}

Response Fields

Field	Type	Description
`id`	string	Unique job ID
`title`	string	Job title
`description`	string	Full job description
`company`	object	Company information
`location`	object	Job location details
`employment_type`	string	Type: `full-time`, `part-time`, `contract`, `internship`
`salary`	object	Salary range information
`requirements`	object	Job requirements and qualifications
`posted_at`	string	When job was posted (ISO 8601)
`application_url`	string	URL to apply for the job
`views`	integer	Number of views
`applications`	integer	Number of applications

Common Use Cases

Job Details Page: Display complete job information
Application Tracking: Monitor application counts and views
Job Aggregation: Collect job data for job boards
Company Research: Get company information from job postings

Search Jobs

Searches for jobs based on keywords, location, company, and various filters. This is the primary endpoint for job discovery.

Endpoint: GET /jobs/search

Query Parameters

Name	Type	Required	Description
`q`	string	No	Search query (keywords, skills, job title)
`location`	string	No	Location filter (city, state, country)
`company`	string	No	Company name or username
`employment_type`	string	No	Filter: `full-time`, `part-time`, `contract`, `internship`, `remote`
`experience_level`	string	No	Filter: `entry`, `mid`, `senior`, `executive`
`salary_min`	integer	No	Minimum salary
`salary_max`	integer	No	Maximum salary
`posted_since`	string	No	Jobs posted since date (ISO 8601: YYYY-MM-DD)
`limit`	integer	No	Number of results (Default: 20, Max: 100)
`cursor`	string	No	Pagination cursor

Request Examples

# Search for software engineer jobs
curl --request GET \
  --url 'https://<direct.gateway>/jobs/search?q=software%20engineer&limit=20' \
  --header 'X-API-KEY: YOUR_API_KEY'
 
# Search remote jobs in tech
curl --request GET \
  --url 'https://<direct.gateway>/jobs/search?q=developer&employment_type=remote&limit=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

// Search jobs
const params = new URLSearchParams({
  q: 'software engineer',
  location: 'San Francisco',
  employment_type: 'full-time',
  experience_level: 'senior',
  limit: 20
});
 
const response = await fetch(`https://<direct.gateway>/jobs/search?${params}`, {
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});
const jobs = await response.json();

Python:

import requests
 
params = {
    'q': 'software engineer',
    'location': 'San Francisco',
    'employment_type': 'full-time',
    'experience_level': 'senior',
    'limit': 20
}
 
response = requests.get(
    'https://<direct.gateway>/jobs/search',
    params=params,
    headers={'X-API-KEY': 'YOUR_API_KEY'}
)
jobs = response.json()

Response Example

{
  "data": [
    {
      "id": "1234567890123456789",
      "title": "Senior Software Engineer",
      "company": {
        "name": "Tech Company Inc.",
        "username": "techcompany",
        "verified": true
      },
      "location": {
        "city": "San Francisco",
        "state": "CA",
        "remote_allowed": true
      },
      "employment_type": "full-time",
      "salary": {
        "min": 120000,
        "max": 180000,
        "currency": "USD"
      },
      "posted_at": "2024-10-01T10:00:00.000Z"
    }
  ],
  "meta": {
    "result_count": 20,
    "next_cursor": "eyJpZCI6IjEyMzQ1Njc4OTAxMjM0NTY3ODkifQ=="
  }
}

Search Tips

Use specific keywords: More specific terms yield better results
Combine filters: Use multiple filters to narrow results
Location flexibility: Try city, state, or country for location
Employment type: Use remote to find remote positions

Get Jobs by Company

Retrieves all job listings from a specific company. Useful for company career pages and recruitment tracking.

Endpoint: GET /company/{company_id}/jobs

Path Parameters

Name	Type	Required	Description
`company_id`	string	Yes	Company user ID or username

Query Parameters

Name	Type	Required	Description
`limit`	integer	No	Number of results (Default: 20, Max: 100)
`cursor`	string	No	Pagination cursor
`active_only`	boolean	No	Only active/open positions (Default: true)

Request Examples

# Get all jobs from a company
curl --request GET \
  --url 'https://<direct.gateway>/company/techcompany/jobs?limit=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

const response = await fetch(
  'https://<direct.gateway>/company/techcompany/jobs?active_only=true&limit=20',
  { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
);
const jobs = await response.json();

Response Example

{
  "company": {
    "id": "987654321",
    "name": "Tech Company Inc.",
    "username": "techcompany"
  },
  "jobs": [
    {
      "id": "1234567890123456789",
      "title": "Senior Software Engineer",
      "employment_type": "full-time",
      "location": {
        "city": "San Francisco",
        "remote_allowed": true
      },
      "posted_at": "2024-10-01T10:00:00.000Z"
    }
  ],
  "meta": {
    "total_jobs": 45,
    "active_jobs": 32,
    "result_count": 20,
    "next_cursor": "..."
  }
}

Use Cases

Company Career Pages: Display all jobs from a company
Recruitment Tracking: Monitor company hiring activity
Competitor Analysis: Track competitor job postings

Get Company Information

Retrieves detailed information about a company, including profile, description, location, and employee count.

Endpoint: GET /company/{company_id}

Path Parameters

Name	Type	Required	Description
`company_id`	string	Yes	Company user ID or username

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/company/techcompany' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Example

{
  "id": "987654321",
  "name": "Tech Company Inc.",
  "username": "techcompany",
  "description": "Leading technology company focused on innovation",
  "website": "https://techcompany.com",
  "location": {
    "city": "San Francisco",
    "state": "CA",
    "country": "United States"
  },
  "employee_count": "1000-5000",
  "industry": "Technology",
  "founded": 2010,
  "logo_url": "https://pbs.twimg.com/profile_images/...",
  "verified": true,
  "total_jobs_posted": 145,
  "active_jobs": 32
}

Response Fields

Field	Type	Description
`id`	string	Company user ID
`name`	string	Company name
`username`	string	Company Twitter username
`description`	string	Company description
`website`	string	Company website URL
`location`	object	Company location
`employee_count`	string	Employee count range
`industry`	string	Industry sector
`founded`	integer	Year founded
`verified`	boolean	Whether company is verified
`total_jobs_posted`	integer	Total jobs posted
`active_jobs`	integer	Currently active job postings

Employment Types

Jobs can have different employment types:

Type	Description
`full-time`	Full-time permanent position
`part-time`	Part-time position
`contract`	Contract-based work
`internship`	Internship position
`remote`	Remote work position
`hybrid`	Combination of remote and on-site

Experience Levels

Jobs are categorized by experience level:

Level	Description
`entry`	Entry-level, 0-2 years experience
`mid`	Mid-level, 2-5 years experience
`senior`	Senior-level, 5+ years experience
`executive`	Executive/C-level positions

Best Practices

Jobs-Specific Tips

Use specific filters: Narrow results with location, employment_type, and salary filters
Cache job data: Jobs don't change frequently, cache for 10-15 minutes
Handle missing fields: Some job fields are optional - handle gracefully in your application
Use search efficiently: Combine multiple filters to reduce need for multiple searches

For general API best practices including error handling, rate limits, and performance optimization, see our Best Practices Guide.

3. Monitor New Jobs

Track new job postings for companies:

async function getNewJobs(companyId, sinceDate) {
  const response = await fetch(
    `/company/${companyId}/jobs?posted_since=${sinceDate}`,
    { headers: { 'X-API-KEY': API_KEY } }
  );
  const jobs = await response.json();
  
  return jobs.data.filter(job => 
    new Date(job.posted_at) > new Date(sinceDate)
  );
}

4. Pagination Handling

Implement proper pagination for large result sets. See our Pagination Guide for detailed examples and best practices.

For comprehensive error handling and rate limits information, see our guides:

Error Handling Guide - Complete error handling reference
Rate Limits Guide - Rate limit details and management

Troubleshooting

Issue	Symptoms	Possible Causes	Solutions
No jobs found in search	Search returns empty results	Search terms too specific, filters too restrictive, no jobs match criteria	Broaden search terms, remove some filters, try different location or company filters
Job data incomplete	Missing fields in job response	Company didn't provide all information, job posting is incomplete, some fields are optional	Some fields are optional and may not always be present - check if job is still active, handle missing fields gracefully in your application

FAQ

How often are job listings updated?

Job listings are updated in real-time. New jobs appear immediately, and removed jobs are removed from results.

Can I get historical job data?

The API provides current job listings. For historical data, you would need to track jobs over time yourself.

Are all jobs available through the API?

The API provides access to jobs posted on Twitter's job platform. Some companies may post jobs elsewhere.

How do I filter for remote jobs?

Use employment_type=remote in your search query to find remote positions.

Can I get application status?

The API provides job information and application URLs, but application status tracking is handled by the company's application system.

How accurate is salary information?

Salary information is provided by companies and may vary. Some jobs may not include salary information.

Users Endpoints - Get company user information
Search Endpoints - Search for job-related tweets
Using Pagination Cursors - Pagination guide
Error Handling Guide - Error handling
Rate Limits Guide - Rate limits
Best Practices - API best practices

Lists & Communities Using Pagination Cursors

Overview

Key Features

Authentication

Endpoints

Get Job by ID

Path Parameters

Request Examples

Response Example

Response Fields

Common Use Cases

Search Jobs

Query Parameters

Request Examples

Response Example

Search Tips

Get Jobs by Company

Path Parameters

Query Parameters

Request Examples

Response Example

Use Cases

Get Company Information

Path Parameters

Request Example

Response Example

Response Fields

Employment Types

Experience Levels

Best Practices

Jobs-Specific Tips

3. Monitor New Jobs

4. Pagination Handling

Troubleshooting

FAQ

How often are job listings updated?

Can I get historical job data?

Are all jobs available through the API?

How do I filter for remote jobs?

Can I get application status?

How accurate is salary information?

Related Documentation