find-marketing-agency
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.
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 addSERVICEGRAPH_API_KEY=vk_…to.env.localhere (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 cparses asa OR (b AND c). Use parens. - Comma list = OR within one predicate.
state:CA,NY,TX= any of three. - Negation is
-xorNOT x.state:CA,-NYis rejected; usestate: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.
Recipes
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/