04 Theirstack Jobs

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

Prerequisites

• THEIRSTACK_API_KEY in env or .env - get one at 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):

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:

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; this skill only gathers the facts.

Output contract

Each run writes runs/<run-id>/ per headless-gtm-shared/CONVENTIONS.md:

runs/<run-id>/
├── records.jsonl     # one line per domain - what the chain consumes
├── records.csv       # human export (derived)
├── domains/*.json    # per-domain cache: curated jobs + query hash
├── tracker.json      # resume state
├── filters.json      # the exact API filters used
└── meta.json         # counts, credits estimate, balance before/after

Records are additive: upstream fields pass through untouched, domain is normalized (lowercase, no www., no scheme), filters_matched unions. Fields this skill adds: open_roles_count, roles_window_days, roles_title_filter, jobs[] (title, url, date_posted, location, remote, seniority, salary, hiring_team, description_snippet), plus free firmographics when present: employee_count, funding_stage, total_funding_usd, industry, company_hq. Real example (trimmed):

{"company": "Stripe", "domain": "stripe.com", "person": null, "open_roles_count": 2, "roles_window_days": 30, "jobs": [{"title": "Sales Development Representative", "url": "https://stripe.com/jobs/search?gh_jid=8083685", "date_posted": "2026-07-24", "location": "Dublin", "seniority": "mid_level"}], "employee_count": 16807, "funding_stage": "secondary_market", "filters_matched": ["2 open 'SDR,BDR' role(s) in last 30d (latest 2026-07-24)", "hiring: Sales Development Representative; Head of Sales Development, AMER"]}

Domains checked with zero matches still get a record (open_roles_count: 0, a "no open roles" line in filters_matched) - downstream needs to distinguish checked-and-quiet from never-checked.

Key behaviors

• The API requires at least one of: a posting-age filter, a company domain filter, or a company name filter. The script always sends posted_at_max_age_days, so any filter combination on top is valid.
• Domain matching is exact; name matching (--names is deliberately not exposed - pass domains) is fuzzy and pulls false positives.
• Discover mode refuses to run without at least --title, --seniority, or --tech - an unfiltered pull of every recent posting is never worth credits.
• Observed enum values: seniority = junior / mid_level / senior / c_level; funding_stage includes seed, series_a..., and secondary_market for late-stage. Treat as observed, not exhaustive.
• hiring_team (name, title, LinkedIn) is present on some postings - when it is, that person is a resolution shortcut for 06.
• The balance endpoint (/v0/billing/credit-balance) is undocumented but live; if it ever disappears the script degrades to a dashboard pointer.
• Results order newest-first; discover mode's --max-jobs ceiling therefore keeps the freshest postings.

Chain handoff

• 05-signal-builder: pass the run's records file via --records runs/<run-id>/records.jsonl. Open-req evidence usually lands as a WHEN/timing signal; 05 owns the 1-10 score and approach call.
• 04-crustdata-signals: run both when the play needs open reqs AND recent joins/funding - same records.jsonl in, additive fields out, 05 merges by domain.
• 06-resolution-email-person: hiring_team entries and senior req titles ("Head of Sales") tell 06 who to resolve.
• email-writer: filters_matched lines are situation-line raw material ("saw you're hiring your first SDRs...").

Scope boundaries

References

• references/jobs-api.md - full filter list, response fields, free-count recipe, curl examples, verified credit mechanics
• TheirStack API docs - the vendor source of truth