# ServiceGraph

> Datasets for founders. Where to launch, who to email, who to hire. Curated, enriched lists of product directories, business directories, newsletters, and agencies — with traffic, DR, subscribers, and ratings attached. Browse free. Details for credits. 2,000 free on signup.

ServiceGraph publishes the structured rows behind questions like "which SaaS directories actually rank, and what's their submission policy?", "show me US tech newsletters with 5k+ subs", or "shortlist three boutique IP law firms in California rated 4+." Each row is enriched with the metric set that matters for that dataset (DR, monthly traffic, subscriber estimates, ratings, contact details). Browse, search, and filter are free; per-row detail is a paid unlock.

## Datasets (live)

- **product directories** — 850+ rows. Submission policy, DR, organic traffic, monthly visits, contact.
- **business directories** — 3,500+ rows. Niche, DR, organic traffic, organic keywords, backlinks.
- **newsletters** — 50k+ rows. Platform (Substack/Beehiiv/Ghost/self-hosted), language, paywall signal, post cadence, monthly visits, subscriber estimate.
- **agencies (US professional services)** — 110k+ rows. Industry, services, location, size, ratings, third-party listings (Clutch / G2 / GoodFirms / DesignRush).

Each dataset has its own schema (which fields are returned in the free brief, which are paid detail) and its own filter set. Discover them via `GET /v1/datasets`; expand schema via `GET /v1/datasets/:id`.

## Datasets (coming soon)

- subreddits — communities, subs, post activity
- influencers — creators by niche, followers, engagement

## Pricing

- 2,000 free credits on signup (no card). ≈ 200 row unlocks.
- 1,000 credits = $10 (pay-as-you-go).
- 10,000 credits = $80 (20% off at volume).
- 1 row unlock = 10 credits on current datasets, ≈ $0.10/row, ≈ $0.08 at volume. Unlocks last 30 days; re-unlock after that. Credits don't expire.

Browse / search / filter is free regardless of credits.

## For AI-agent owners

- [Install as a Claude Code skill](https://github.com/nostrband/servicegraph): `npx skills add https://github.com/nostrband/servicegraph --skill find-service-providers`
- [Skill source code](https://github.com/nostrband/servicegraph)

## API

- API base: https://api.servicegraph.co
- [OpenAPI 3.1 spec](https://api.servicegraph.co/openapi.json)
- [Console & full docs](https://docs.servicegraph.co)
- Get an API token at [servicegraph.co/profile/api-keys](https://servicegraph.co/profile/api-keys) and pass it as `Authorization: Bearer <token>` on every `/v1/*` call.

## Endpoints (summary)

Discovery:

- `GET /v1/datasets` — list of datasets + row counts + per-unlock price.
- `GET /v1/datasets/:id` — full schema for one dataset: brief field specs (free, returned in search), detail field specs (returned only when the caller has an active unlock), allowed filters, per-unlock price + TTL.

Search + fetch:

- `GET /v1/datasets/:id/search?filter=...` — search inside one dataset. Returns brief rows + per-row `unlock` state. Filter syntax below; `kind:` predicates are rejected because the URL is authoritative.
- `GET /v1/datasets/:id/:apex` — fetch one row. Always returns the brief; `data.detail` is non-null only when the caller has an active unlock for `(user, dataset_id, apex)`. Idempotent — never charges.
- `POST /v1/datasets/:id/unlocks` — atomically unlock detail for one or more rows. Body: `{"apexes": ["a.com","b.com"]}`. All uncached apexes unlock together or none do (HTTP 402 if balance < total cost). Already-unlocked rows return `was_cached:true` with `charged:0`.

DSL helpers (dataset-scoped):

- `GET /v1/datasets/:id/fields` — filter field catalog for one dataset + DSL grammar string. Pass `?include_values=1` to inline value lists. Prime an agent's session with one call.
- `GET /v1/datasets/:id/values/:field` — enumerate distinct values for one filter field, scoped to rows in this dataset. Pagination via `limit` + `offset`; substring filter via `q`.
- `GET /v1/datasets/:id/check?filter=...` — validate a filter string against this dataset (parse + field-whitelist check). Returns `{valid, normalized}` or `{valid:false, error}`.
- `POST /v1/datasets/:id/translate-intent` — plain-English intent → DSL filter via a fast LLM grounded in the live tag taxonomy for this dataset.

Account:

- `GET /v1/me` — identity, plan, usage.
- `GET /v1/me/credits` — current credit balance.
- `GET /v1/me/credits/transactions` — paginated spend history. Unlock charges carry the `(dataset_id, apex, expires_at)` tuple they bought.

## Filter DSL (one query parameter)

GitHub-search-style. AND binds tighter than OR; `-x` or `NOT x` for negation; `tag@evidence` qualifier for tag-set fields with evidence (e.g. `service_provided`). Any bareword (a word or number with no operator) becomes a free-text keyword search across the dataset's text columns.

Examples (per dataset):

- agencies: `industry:legal state:CA,NY -company_size_signal:solo`
- agencies: `industry:management_consulting service_provided:strategy-consulting@high`
- agencies: `rating>=4 review_count_total>=20 has:clutch`
- agencies: `dental industry:marketing_agency` (bareword → keyword:dental)
- agencies: `(web3 OR blockchain) state:CA`
- business directories: `dr>=60 organic_traffic>=10000`
- product directories: `AI niche:tools`
- newsletters: `platform:substack language:en paywall_signal=0`

The set of legal fields differs per dataset — call `GET /v1/datasets/:id/fields` to see what's available. Filters that reference fields outside a dataset's whitelist are rejected at `/check` time.

## Identifier conventions

- `apex` — eTLD+1, lowercased, no trailing dot (e.g. `animalz.co`). Used as the per-row identifier in URLs and unlocks.
- `dataset_id` — the URL segment for a dataset (`pro_services`, `business_directory`, `product_directory`, `newsletter`, `job_board`, `marketplace`). Stable; safe to hardcode in agents.

## Optional

- [Site](https://servicegraph.co)
- Contact: artur@servicegraph.co