find-marketing-agency

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.

1. Just try the call through a shell wrapper that sources

.env.local:

``bash ( 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' ) ``

1. 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."

1. 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:

1. AND binds tighter than OR. a OR b c parses as a OR (b AND c). Use parens.
2. Comma list = OR within one predicate. state:CA,NY,TX = any of three.
3. Negation is -x or NOT x. state:CA,-NY is rejected; use state:CA -state:NY.
4. 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/