Use whenever the user wants to find, shortlist, vet, or enrich US marketing agencies — including branding, content marketing, PPC/paid media, social media, email marketing, performance/demand-gen, video production, and full-service digital agencies. Triggers on requests like "shortlist three B2B branding agencies in California", "find a PPC shop with ecommerce experience", "we need a content marketing partner for a SaaS launch", or "pull contact info for these 12 agency domains", even when the need is described indirectly. Drives the ServiceGraph API (api.servicegraph.co) — a 100k+ US firm catalog filterable by industry, services, location, size, ratings, and third-party listings. Skip SEO-only asks (use find-seo-agency), web/software-development asks (use find-web-developer or find-software-developer), recruiting an in-house marketing hire, "write me a marketing plan" do-the-work asks, non-US firms, individual freelancers, marketing-software-product recommendations, and consumer/personal-brand asks.
Use whenever the user wants to find, shortlist, vet, or enrich US marketing agencies — including branding, content marketing, PPC/paid media, social media, email marketing, performance/demand-gen, video production, and full-service digital agencies. Triggers on requests like "shortlist three B2B branding agencies in California", "find a PPC shop with ecommerce experience", "we need a content marketing partner for a SaaS launch", or "pull contact info for these 12 agency domains", even when the need is described indirectly. Drives the ServiceGraph API (api.servicegraph.co) — a 100k+ US firm catalog filterable by industry, services, location, size, ratings, and third-party listings. Skip SEO-only asks (use find-seo-agency), web/software-development asks (use find-web-developer or find-software-developer), recruiting an in-house marketing hire, "write me a marketing plan" do-the-work asks, non-US firms, individual freelancers, marketing-software-product recommendations, and consumer/personal-brand asks.
Drive the ServiceGraph API (https://api.servicegraph.co) to find,
shortlist, and enrich US marketing agencies via the pro_services
dataset. The catalog has tens of thousands of US marketing firms
tagged across ~26 service sub-tags including branding,
content-marketing, ppc, social-media-marketing, email-marketing,
web-design, video-production, inbound-marketing,
marketing-strategy, conversion-optimization, and
ecommerce-marketing. (Note: there is no performance-marketing or
demand-gen / demand-generation tag — those user-phrasings map to
inbound-marketing / marketing-strategy / conversion-optimization
plus a keyword fallback.)
Always pin industry:marketing_agency. This skill exists to do
that automatically — the user shouldn't have to think about catalog
taxonomy.
Any HTTP client works (curl, fetch, requests). Examples below use curl.
Sibling skills — defer when scope is narrow
If the user's ask is strictly one of the following, defer to the
dedicated skill:
Strictly SEO/search-ranking work → find-seo-agency
Strictly web/app/software development → find-web-developer /
find-software-developer
If the user wants a marketing agency that also does SEO or web work
as part of a broader engagement, this skill is correct — pin
industry:marketing_agency and add the relevant service_provided:
tags.
Prerequisites
ServiceGraph access, either:
the ServiceGraph MCP server (https://mcp.servicegraph.co) loaded in
your harness — this plugin's .mcp.json wires it up; OAuth 2.1 + PKCE
keeps credentials in the harness sandbox — or
a ServiceGraph API key (vk_…, minted at
https://servicegraph.co/profile/api-keys) available as
in the environment or for the REST
path (setup steps under Auth below).
SERVICEGRAPH_API_KEY
.env.local
An HTTP client for the REST path — the examples use curl.
Instructions
The loop is free-first: discovery, validation, search, and brief reads cost
nothing; only unlock after the user confirms the spend.
Pick the call path — the ServiceGraph MCP tools if loaded, otherwise the
REST flow (MCP server and Auth sections below).
GET /v1/datasets/pro_services/fields?include_values=1 — confirm the
fields and values you plan to filter on exist.
Build the filter (Filter DSL below) and validate it with
GET /v1/datasets/pro_services/check — or draft it from plain English via
POST /v1/datasets/pro_services/translate-intent.
GET /v1/datasets/pro_services/search — present the free brief cards and
let the user pick.
Quote the unlock cost (10 credits per row, 30-day TTL) and get an explicit
go-ahead.
POST /v1/datasets/pro_services/unlocks with the chosen apexes; report the
revealed detail.
GET /v1/me/credits to report the remaining balance when asked.
MCP server (preferred for authed calls)
If your harness has the ServiceGraph MCP server loaded (recognizable
by tool names containing servicegraph), prefer those tools — the
harness handles credentials in its own sandbox via OAuth 2.1 + PKCE,
so no token enters LLM context. Otherwise use the REST flow below.
API surface (dataset id: pro_services)
Every endpoint requires the bearer (Authorization: Bearer vk_…).
There is no anonymous tier.
Endpoint
Cost
Use it for
GET /v1/datasets/pro_services/fields[?include_values=1&q=]
free
Filter-field catalog + DSL grammar. Call first per session.
GET /v1/datasets/pro_services/values/:field[?q=&limit=]
free
Enumerate values for one field.
GET /v1/datasets/pro_services/check?filter=…
free
Validate a filter. Returns {valid, normalized} or {valid:false, error}.
On 401 unauthorized, prompt the user (don't accept the key in chat):
"Open https://servicegraph.co/profile/api-keys, sign in,
click Create key, and copy the vk_… value. Then add
SERVICEGRAPH_API_KEY=vk_… to .env.local here (or export it
in your shell). Tell me when done. Please don't paste the key
into chat."
Retry the same call after the user signals ready. A later 401
means the key was rotated/revoked — re-prompt.
Filter DSL
GitHub-search-style.
filter := orExpr
orExpr := andExpr ("OR" andExpr)*
andExpr := notExpr (("AND")? notExpr)* # whitespace = implicit AND
notExpr := ("NOT" | "-") notExpr | atom
atom := "(" filter ")" | predicate
predicate:= IDENT op valueOrList | bareword
op := ":" | "=" | ">=" | "<=" | ">" | "<"
valueOrList := value ("," value)*
value := IDENT | NUMBER | tagAtEvidence
tagAtEvidence := IDENT "@" ("low"|"medium"|"high")
bareword := IDENT | NUMBER # → keyword:<bareword>
Four rules that bite:
AND binds tighter than OR.a OR b c parses as a OR (b AND c). Use parens.
Comma list = OR within one predicate.state:CA,NY,TX = any of three.
Negation is -x or NOT x.state:CA,-NY is rejected; use state:CA -state:NY.
Bareword = keyword search. Free-text substring across name / brand / title / meta / legal_name. Multiple barewords AND. Wrap multi-word phrases in double quotes (keyword:"foo bar").
Marketing-flavored examples (validate yours with /check):
industry:marketing_agency service_provided:branding@high
industry:marketing_agency service_provided:ppc service_provided:content-marketing
industry:marketing_agency state:CA,NY -company_size_signal:solo
industry:marketing_agency (service_provided:inbound-marketing@high OR service_provided:marketing-strategy@high)
b2b industry:marketing_agency service_provided:content-marketing@high
industry:marketing_agency rating>=4 review_count_total>=20 has:clutch
industry:marketing_agency NOT (service_provided:seo OR service_provided:web-development)
Identifying firms — apex
Firms are identified by their apex domain (ogilvy.com, not
www.ogilvy.com/about). Strip user-supplied URLs to the apex before
calling :apex endpoints or building unlock batches.
Output
All responses are JSON.
Search returns free brief firm cards — apex, name, location, and
rating signals — plus a per-row unlock hint and the match total. Briefs
never include url, phone_primary, email_primary, legal_name,
address_full, or the full platforms map.
Unlock (POST …/unlocks) returns each unlocked firm's detail block —
contact fields, address, socials, the platforms map — plus per-item
billing; detail stays readable for 30 days.
Errors arrive as a JSON envelope
{"error": {"code": "…", "message": "…"}} — see Errors below.
Examples
A. Branding agency in a state
User: "Three B2B branding agencies in California for a Series-A SaaS company."
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+state:CA+service_provided:branding@high+b2b&limit=10
# → 10 brief cards + total + per-row unlock.status
# Present, get user's pick of 3. "Unlocking 3 = 30 credits, 30-day TTL."
POST /v1/datasets/pro_services/unlocks
{ "apexes": ["firm-a.com", "firm-b.com", "firm-c.com"] }
# → brief + detail for all 3
B. PPC + ecommerce vertical
User: "PPC shop that specializes in ecommerce."
The catalog has a real ecommerce-marketing tag — pin it alongside
PPC for tighter shortlists than relying on the ecommerce keyword
alone:
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:ppc+service_provided:ecommerce-marketing&limit=10
C. Multi-tag intersection — content + email + B2B vertical
User: "Content marketing partner for a SaaS launch — should also do email."
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:content-marketing@high+service_provided:email-marketing+saas
If the NY-area pool collapses with a fintech/saas keyword (it
tends to — vertical pins under-perform on agency copy), drop the
keyword and surface vertical experience to the user from briefs.
D. Performance / demand-gen (indirect intent)
User: "Someone to run our quarterly demand-gen campaigns and own the funnel."
The catalog has noperformance-marketing / demand-gen /
demand-generation tag — map to inbound-marketing,
marketing-strategy, or conversion-optimization, plus a keyword
for the user's wording:
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+(service_provided:inbound-marketing@high OR service_provided:marketing-strategy@high OR service_provided:conversion-optimization@high)+(demand OR funnel)&limit=10
If breakdowns are thin, drop @high or fall back to pure keyword.
Alternatively, use the intent translator:
POST /v1/datasets/pro_services/translate-intent
{ "intent": "agency to run quarterly demand-gen campaigns and own the funnel" }
E. Quality threshold (third-party signals)
User: "Compare three social media agencies that have worked with Fortune 500 — high evidence."
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:social-media-marketing@high+rating>=4+review_count_total>=20+has:clutch&limit=10
fortune 500 is hard to filter structurally; let the user pick from
briefs or add fortune as a keyword.
F. DTC ecommerce agencies
User: "Paid-social agency for our DTC apparel brand."
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:ecommerce-marketing+service_provided:social-media-marketing+dtc&limit=10
G. Video production
User: "Video production studio for a 90-second product launch film, NYC or LA."
GET /v1/datasets/pro_services/search?filter=industry:marketing_agency+service_provided:video-production+state:NY,CA&limit=10
State is HQ-only; surface city from the unlocked detail for NYC-vs-LA disambiguation.
H. BYO apex list — enrich domains
User pastes 8–20 domains:
GET /v1/datasets/pro_services/:apex per domain — free brief
(404 = not in catalog, no charge). Flag misses.
User picks N to fully enrich. POST /unlocks with all of them =
10×N credits, single atomic charge, detail bundles returned.
Within 30-day TTL, repeated unlock POSTs are free.
Gotchas
Always pin industry:marketing_agency. Without it, service_provided:branding matches design firms, IT services, and others.
Defer to sibling skills for narrow asks. SEO-only → find-seo-agency. Strictly web/app development → find-web-developer / find-software-developer.
Briefs DO include apex, name, industry, service_provided, state, ratings. They DON'T include url, phone_primary, email_primary, legal_name, address_full, full platforms. Those require an unlock.
not_found / not_in_dataset 404 is not a bug. Apex isn't in pro_services (might be in another dataset). Skip; not charged.
Catalog is US-only B2B. Refuse non-US asks, individual freelancers, and personal-brand consulting for the user themselves.
Multi-word phrases must be split or quoted.b2b saas parses as two AND'd keywords; "b2b saas" is one phrase.
Unlock is atomic.POST /unlocks with 5 apexes either charges (up to) 50 credits or leaves balance untouched on 402. Plan the batch.
Within-TTL re-views are free. Re-running unlock on an apex still inside its 30-day window returns was_cached:true.
position included; fix and re-validate with /check.
400
kind_in_filter
Strip any kind: from filter — URL is authoritative.
400
field_not_in_dataset
Field isn't allowed on pro_services; drop it.
400
invalid_apex
Re-normalize to apex.
401
unauthorized / invalid_audience
Re-prompt for a fresh vk_….
402
insufficient_credits
needed and balance in payload; nothing charged.
404
not_found / not_in_dataset
Skip; not charged.
429
rate_limited
Honor Retry-After.
End-to-end example
User: "Shortlist three B2B branding agencies in California for a
Series-A SaaS company — high evidence on branding, ideally with at
least a 4-star rating."
# 1. Discover (once per session)
GET /v1/datasets/pro_services/fields?include_values=1
# Confirms 'branding' is in service_provided, rating is numeric.
# 2. Validate + scope (free)
GET /v1/datasets/pro_services/check?filter=industry:marketing_agency+state:CA+service_provided:branding@high+rating>=4+b2b
# 3. Search briefs (free)
GET /v1/datasets/pro_services/search?filter=...&limit=10
# → 10 cards + total + per-row unlock.status
# 4. Present, get pick of 3. "Unlocking 3 firms = 30 credits, 30-day TTL."
# 5. Atomic unlock (charges 30 credits)
POST /v1/datasets/pro_services/unlocks
{ "apexes": ["firm-a.com", "firm-b.com", "firm-c.com"] }
# 6. (Optional) Confirm balance
GET /v1/me/credits
