PullData
API Reference

One API key, three scraper payload shapes, and clean job controls.

Use the Pulldata developer API to run Google Maps, Contact Details, and Google Search Results jobs from your own app. Authenticate with a bearer API key, submit a payload, then poll or export the results.

Start FreeOpen Dashboard

Authentication

All developer endpoints use the same credits and permissions as the key owner.

Auth Header
Authorization: Bearer YOUR_API_KEY
Base URL
https://pdb.pulldata.io/api/developer/v1
Rate Limiting

Every request is checked against requests per minute. Job creation also checks requested rows per second and your plan's concurrent developer-job cap.

Start Job Payload

Use these request bodies with POST /jobs or POST /jobs/sync.

Google Maps
Use locations or pincodes, categories, and optional email enrichment.
Google Maps JSON Body
{
  "scraperId": "google-maps",
  "inputParams": {
    "locations": ["Mumbai, India"],
    "categories": ["restaurants"],
    "max_leads_per_query": 50,
    "max_total_results": 150,
    "scrape_emails": true
  },
  "webhookUrl": "https://your-app.example/webhooks/pulldata"
}
Contact Details
Send company websites or domains and let the contact-details worker enrich contacts in parallel.
Contact Details JSON Body
{
  "scraperId": "contact-details",
  "inputParams": {
    "websites": [
      "https://www.nandos.co.in",
      { "domain": "zomato.com", "extra": { "priority": "high" } }
    ],
    "maxWorkers": 12,
    "refreshCache": false
  }
}
Google Search Results
Search multiple queries for one region and control output with limit or max_leads_per_query.
Google Search Results JSON Body
{
  "scraperId": "google-search-results",
  "inputParams": {
    "searchQueries": ["restaurants in delhi", "cafes in gurgaon"],
    "location": "India",
    "limit": 20
  }
}
scraperId
Supported values are google-maps, contact-details, and google-search-results.
inputParams.locations | pincodes
Google Maps accepts either field, along with categories and optional scrape_emails.
inputParams.websites
Contact Details accepts raw URLs or objects with website, url, or domain.
inputParams.searchQueries | search_queries
Google Search Results accepts either camelCase or snake_case query arrays plus location.
inputParams.max_leads_per_query / limit
Controls per-query row output and affects row-budget enforcement.
webhookUrl
Optional callback invoked when the job reaches a terminal state.

Endpoints

Every currently available developer endpoint with a ready-to-use curl snippet.

GET/me

Get caller context

Returns the user, plan, credits balance, and API key metadata for the current request.

Auth
Bearer API key
GET /me
curl "https://pdb.pulldata.io/api/developer/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"
GET/credits/balance

Get remaining credits

Returns the current credits available for the account that owns the API key.

Auth
Bearer API key
GET /credits/balance
curl "https://pdb.pulldata.io/api/developer/v1/credits/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"
GET/scrapers

List available scrapers

Lists enabled scrapers that can be called through the developer API.

Auth
Bearer API key
GET /scrapers
curl "https://pdb.pulldata.io/api/developer/v1/scrapers" \
  -H "Authorization: Bearer YOUR_API_KEY"
GET/scrapers/:slug

Get scraper details

Returns a single scraper definition including configuration and cost details.

Auth
Bearer API key
GET /scrapers/:slug
curl "https://pdb.pulldata.io/api/developer/v1/scrapers/google-maps" \
  -H "Authorization: Bearer YOUR_API_KEY"
POST/jobs

Start a scraping job (Asynchronous)

Queues a scraping job asynchronously. Use the same endpoint for Google Maps, Contact Details, and Google Search Results by changing scraperId and the payload shape.

Auth
Bearer API key
POST /jobs
curl -X POST "https://pdb.pulldata.io/api/developer/v1/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scraperId": "google-maps",
  "inputParams": {
    "locations": ["Mumbai, India"],
    "categories": ["restaurants"],
    "max_leads_per_query": 50,
    "max_total_results": 150,
    "scrape_emails": true
  },
  "webhookUrl": "https://your-app.example/webhooks/pulldata"
}'
POST/jobs/sync

Start a scraping job (Synchronous)

Executes a short-running scraping job synchronously. Use this for smaller jobs when you want the final payload inline instead of polling later.

Auth
Bearer API key
POST /jobs/sync
curl -X POST "https://pdb.pulldata.io/api/developer/v1/jobs/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scraperId": "contact-details",
  "inputParams": {
    "websites": [
      "https://www.nandos.co.in",
      { "domain": "zomato.com", "extra": { "priority": "high" } }
    ],
    "maxWorkers": 12,
    "refreshCache": false
  }
}'
GET/jobs

List jobs

Returns paginated jobs created by the current account. Supports optional query parameters: page, limit, status, and scraperId.

Auth
Bearer API key
GET /jobs
curl "https://pdb.pulldata.io/api/developer/v1/jobs?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
GET/jobs/:id

Get job details

Returns the full job record including its current status, queue time, worker progress, and the attributed API key.

Auth
Bearer API key
GET /jobs/:id
curl "https://pdb.pulldata.io/api/developer/v1/jobs/YOUR_JOB_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
GET/jobs/:id/results

Get job results

Returns paginated scraped leads for a specific job ID.

Auth
Bearer API key
GET /jobs/:id/results
curl "https://pdb.pulldata.io/api/developer/v1/jobs/YOUR_JOB_ID/results?limit=100&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
GET/jobs/:id/export

Export results

Downloads or returns a signed export URL for csv or json output.

Auth
Bearer API key
GET /jobs/:id/export
curl "https://pdb.pulldata.io/api/developer/v1/jobs/YOUR_JOB_ID/export?format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY"
POST/jobs/:id/cancel

Cancel a job

Requests cancellation of a queued or running job.

Auth
Bearer API key
POST /jobs/:id/cancel
curl -X POST "https://pdb.pulldata.io/api/developer/v1/jobs/YOUR_JOB_ID/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"

Scraper-Specific Docs

Field-level request and response guidance for every scraper available in the library.

Google Maps Scraper

google-maps

Extract local businesses by location and category, then paginate or export rows by job ID.

Required
  • inputParams.locations or inputParams.pincodes
  • inputParams.categories
Optional
  • inputParams.max_leads_per_query
  • inputParams.max_total_results
  • inputParams.scrape_emails
  • inputParams.custom_fields
Result Fields
  • name
  • phone
  • email
  • website
  • address
  • category
  • opening_status
  • opening_hours
  • google_maps_url

Contact Details Scraper

contact-details

Enrich website lists with emails, phones, socials, and crawl metadata.

Required
  • inputParams.websites
Optional
  • inputParams.maxWorkers
  • inputParams.refreshCache
  • inputParams.source
Result Fields
  • website
  • domain
  • primary_email
  • primary_phone
  • emails
  • phone_numbers
  • linkedin
  • facebook
  • instagram
  • pages_crawled

Google Search Results Scraper

google-search-results

Run one or more SERP queries for a location and stream rows as queries complete.

Required
  • inputParams.searchQueries or inputParams.search_queries
  • inputParams.location
Optional
  • inputParams.limit
  • inputParams.max_leads_per_query
  • inputParams.max_total_results
Result Fields
  • keyword
  • title
  • link
  • displayed_link
  • snippet
  • position
  • rich_snippet
Enforced Limits
Requests per minute
Every developer endpoint call consumes request capacity for the API key. Bursty traffic over the configured minute cap returns 429.
Rows per second
Job creation is throttled by the estimated rows requested so heavy jobs cannot starve the worker pool.
Concurrent jobs
Queued and running developer jobs count against your plan concurrency cap before a new job can start.
Common Errors
401 Unauthorized: missing, revoked, or invalid API key.
402 Payment Required: the account has insufficient credits to start the job.
429 Too Many Requests: the key exceeded its request rate, row budget, or plan concurrency limit.
400 Bad Request: the payload does not match the selected scraper shape.
422 or 502 from job start: the worker rejected the payload. Validate required input fields for the selected scraper.
Testing Checklist
  1. 1. Create one key and use it in local or production as needed.
  2. 2. Send Authorization: Bearer YOUR_API_KEY with every request.
  3. 3. Match the payload to the selected scraperId before calling /jobs or /jobs/sync.
  4. 4. Set explicit row limits so throughput controls stay predictable.
  5. 5. Poll GET /jobs/:id until the status is terminal, then fetch results or export.

Get Your API Key

Create keys from the Pulldata dashboard, then use them with the developer endpoints above. The dashboard also exposes usage, credits, job history, and the authenticated API playground.

Create AccountLog In