find-marketing-agency
Overview
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
SERVICEGRAPH_API_KEY in the environment or .env.local for the REST
path (setup steps under Auth below).
- 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}. |
POST /v1/datasets/pro_services/translate-intent | free | {intent} → LLM-generated DSL filter + sanity count. |
GET /v1/datasets/pro_services/search?filter=…&limit=&offset= | free | Brief firm cards + per-row unlock hint + total. |
GET /v1/datasets/pro_services/:apex | free | Single row brief; detail block only if unlocked. |
POST /v1/datasets/pro_services/unlocks | 10 credits / firm | {apexes:[...]} ≤100. Atomic batch; 30-day TTL on detail; was_cached:true rows free. |
GET /v1/me/credits | free | Balance. |
Cost model. Discovery / validation / search / brief reads are
free. Detail (url, phone, email, social, address, full platforms
map) costs 10 credits per firm and lasts 30 days. Re-fetching
an unlocked firm within TTL is free.
Auth
Tokens are vk_* API keys minted in the dashboard.
Keep the token out of the LLM context — never read .env* into
your context; dispatch every authed call through a shell wrapper.
-
Just try the call through a shell wrapper that sources
.env.local:
( set -a; [ -f .env.local ] && . ./.env.local; set +a;
curl -sS -H "Authorization: Bearer $SERVICEGRAPH_API_KEY" \
'https://api.servicegraph.co/v1/datasets/pro_services/fields' )
-
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 no performance-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.
Errors
JSON envelope: {"error": {"code": "...", "message": "..."}}.
| Status | Code | What to do |
|---|
| 400 | filter_parse_error | 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
Resources
