/04-theirstack-jobs

name: 04-theirstack-jobs
description: >
  Pulls open job postings from the TheirStack API and turns them into
  structured hiring signals - open roles per domain, titles, seniority,
  posting dates, hiring team, plus free firmographics (headcount, funding
  stage, industry). Step 04 (signals) of the API-first GTM chain, and the
  discovery entry for hiring-defined ICPs. Use when the user wants hiring
  signals, open reqs, job postings, "who is hiring", "which of these
  companies are hiring X", "find companies hiring Y right now", open-role
  checks on a domain list or records.jsonl, or anything TheirStack. Sizing
  counts bound every pull before spend - free without company filters, ~1
  credit against a domain list - then 1 credit per job returned. For people
  who already joined - recent hires, headcount growth, funding rounds - use
  04-crustdata-signals; for scoring and campaign angles, hand the records
  to 05-signal-builder.

TheirStack Jobs - open-req hiring signals (04)

Open job postings are the "what they're about to do" signal: a company hiring its first SDRs is building outbound, a VP Sales req is a strategy shift, three engineering reqs after a raise is product investment. This skill pulls those postings per company and emits chain records ready for judgment. Its sibling 04-crustdata-signals covers what already happened (funding, joins, headcount); this one covers what's open right now.

Two modes

| Mode | Input | Use when | |---|---|---| | **check** | Domains (`--domains` or an upstream `--records` records.jsonl) | You have a list and want hiring evidence per company - the standard step-04 position in the chain | | **discover** | Filters only (title/seniority/tech + geo/size/funding) | The ICP is the req itself: "companies hiring SDRs in the US right now". This is the direct entry for hiring-defined ICPs - no firmographic superset needed first |

Prerequisites

• `THEIRSTACK_API_KEY` in env or `.env` - get one at

[app.theirstack.com/settings/api](https://app.theirstack.com/settings/api)

• No Python packages required (stdlib only; `python-dotenv` is optional - the

script falls back to reading `.env` itself)

Credit rules

Credits are money. The script's whole flow is built around four facts verified live against the balance ledger (2026-07-24):

| Operation | Cost | |---|---| | Count without company filters (`blur_company_data` + `include_total_results` + limit 1) | 0 credits - exact totals of matching jobs AND companies, free. Discover mode sizing is genuinely free | | Count WITH `company_domain_or` | Blur silently disables on company-identifier filters (HTTP 200, unblurred, billed per returned job). At limit 1 that is ~1 credit per count - and 0 when the domain has no matches. There is no zero-credit domain-scoped count | | Job fetch | 1 credit per job returned, exactly | | Re-fetching a job you already pulled | Charged again - TheirStack has no charge dedup |

Because re-pulls cost full price, every fetched domain is cached as `domains/<domain>.json` keyed by a query hash. Re-running the same query reuses the cache for 0 credits (any prior run folder counts, not just the current one). `--no-cache` forces a refetch.

Every paid pull is preceded by a sizing count, and anything estimated over the gate (default 500 credits, `--credit-gate` to change) stops for confirmation. `--count-only` answers "how many / what would it cost" for 0 credits in discover mode and ~1 credit against a domain list. When the user says "spend nothing", say the ~1-credit floor out loud instead of silently eating it. Ledger postings can lag by minutes - read actual spend from `meta.json`'s `balance_before`/`balance_after` delta after it settles, not from assumptions.

Process

All paths relative to this skill's folder. The script prints the free count and estimate before any spend - no separate estimation step needed.

# Size it first when the user only wants numbers (0 credits)
python3 scripts/theirstack_jobs.py count \
  --domains stripe.com,notion.so --title "SDR,BDR" --days 30

# Check a domain list (per-domain pulls, cached, resumable)
python3 scripts/theirstack_jobs.py check \
  --domains stripe.com,notion.so --title "SDR,BDR,Sales Development" \
  --days 30 --per-domain 10

# Chain position: read domains from an upstream records.jsonl -
# every upstream field carries through into the output records
python3 scripts/theirstack_jobs.py check \
  --records ./runs/<run-id>/records.jsonl \
  --title "Head of Sales,VP Sales,CRO" --days 30

# Discover companies currently hiring for a role
python3 scripts/theirstack_jobs.py discover \
  --title "Revenue Operations,RevOps" --country US \
  --min-employees 50 --max-employees 500 --days 14 --max-jobs 200

# Resume an interrupted run (no double spend - cache + tracker)
python3 scripts/theirstack_jobs.py check --resume --run-dir runs/<run-id>

# Balance
python3 scripts/theirstack_jobs.py credits

Spend levers, in order of effect: `--title` (narrows what counts as a match), `--per-domain` (check-mode cap, default 10), `--max-jobs` (discover-mode ceiling, default 200), `--days` (window, default 30). A company with 50 open roles costs 50 credits uncapped - the caps exist so it costs 10.

Building title filters

`--title` is keyword matching on the title (comma-separated, OR). Compose from what the client's offer makes relevant:

| Signal target | Title keywords | |---|---| | Outbound buildout | SDR, BDR, Sales Development, Outbound | | Sales leadership shift | Head of Sales, VP Sales, CRO, Sales Director | | Marketing motion | Marketing, Growth, Demand Gen, Product Marketing | | RevOps maturity | Revenue Operations, RevOps, Sales Operations, GTM Operations | | Product investment | Engineer, Founding Engineer, CTO, Head of Engineering |

Interpretation stays downstream: multiple same-department reqs = team buildout, a single senior req = strategy change, one junior backfill = weak signal. 05-signal-builder scores this;