Execute a search

Request body ExecuteSearchRequest

Responses

• 200 One result page (and the executed config)
  • results array of object required

    The developers on this page, ordered by the page-local `score` descending, each widened with your account relationship and its enrichment cells.

    max 100 items
    • developer object required

      The developer’s profile.

      • developerId string required

        The stable Vamo identifier for this developer (GitHub's numeric user id, stringified). This is the id every other endpoint takes: facets, reports, contacts, shortlists, steering. Use it, not `login` — a login can be renamed and then belongs to someone else.

        max 64 chars
      • login string required

        The GitHub handle as of the last snapshot. Display it, do not key on it: handles are renameable and reusable.

        max 200 chars
      • name string | null required

        Display name as the developer set it on GitHub. Null when they set none.

        max 200 chars
      • avatarUrl string | null required

        GitHub avatar image URL. Null when absent.

        max 2048 chars
      • currentRole string | null required

        A single free-text role line for the developer. Best-effort and unverified; `professional.title` is the LinkedIn-sourced equivalent when we hold a LinkedIn overlay.

        max 200 chars
      • organization object | null required

        The developer's current employer, when one is known. Null means we hold no employer, NOT that they are unemployed.

        • name string required

          The organization name as recorded.

          max 200 chars
        • logoUrl string | null required

          Organization logo URL, null when absent.

          max 2048 chars
      • university string | null required

        Most recent institution, when the LinkedIn overlay carries education. Null when unknown.

        max 200 chars
      • profiles object required

        Where this developer can be found, plus the addresses if you have already bought them.

        • github string required

          The developer’s github.com profile URL. Always present — GitHub is the identity anchor for every developer in the index.

          max 2048 chars
        • linkedin string | null required

          LinkedIn profile URL when we hold a GitHub↔LinkedIn match for this person. Null for the large majority of developers: only a minority of the indexed GitHub population carries a LinkedIn overlay, so null means "no match held", never "no LinkedIn account".

          max 2048 chars
        • emails array of string

          Every email address we hold for this developer. Present ONLY when this account has already paid to reveal them and the purchase is still within its cache window; a base search or profile read never populates it. ABSENT is not the same as "no email": absent means you have not bought it, while `hasEmail: false` means we hold none. These are addresses we have OBSERVED — from public commit metadata and cached GitHub profile data — and we do not check deliverability, so treat the order as meaningless and expect some to bounce. Buy them with the `contact.emails` facet.

          max 50 items
      • hasEmail boolean required

        Whether we hold at least one email address for this developer. It says we have an address on file, not that the address works — we do not check deliverability. The addresses themselves are never returned by a search or a base profile read: this boolean is the free signal, and the paid `contact.emails` facet is the only way to get them. Use `hasEmail` on a search request to filter to developers we hold an address for, without paying.

      • bio string | null required

        The developer’s GitHub bio, verbatim. Null when empty.

        max 5000 chars
      • location object | null required

        Self-reported location, plus our geocoding of it. Self-reported and never verified against anything: a developer can leave it stale or blank. Null when we hold nothing at all.

        • raw string | null required

          The location string exactly as the developer typed it on GitHub ("SF / remote").

          max 200 chars
        • city string | null required

          City resolved from `raw` by geocoding. Null when `raw` was empty or unresolvable.

          max 200 chars
        • country string | null required

          Country resolved from `raw`. Null when `raw` was empty or unresolvable.

          max 200 chars
      • joinedAt string | null required

        When the GitHub account was created, as an ISO 8601 instant. Null when unknown.

        max 40 chars
      • stats object | null required

        Snapshot counts and standing for this developer. These are from our index and go stale between refreshes; `GET /v1/developers/{id}` returns live GitHub equivalents alongside the contribution garden when you need current numbers. Null when we hold no stats at all.

        • followers integer | null required

          GitHub follower count at snapshot time.

          min 0, max 100000000
        • following integer | null required

          How many accounts this developer follows, at snapshot time.

          min 0, max 100000000
        • totalStars integer | null required

          Sum of stargazers across the repositories ATTRIBUTED to this developer — the same set as `repos`, so the count can never contradict the list. Owned and contributed-to repositories both count; forks do not.

          min 0, max 100000000
        • crackedScore number | null required

          Devrank: a 0–100 standing for this developer within the WHOLE indexed GitHub developer population (tens of millions of accounts), not within a language, region, or seniority peer group — so it is not a like-for-like comparison between two candidates for the same role. It is derived from the follower/contribution graph, is recomputed upstream on its own schedule, and carries no version on the wire, so the same developer can read differently across two snapshots. It contributes one term to the page-local `score` and backs the `levers.github.minDevrank` filter. Null when the developer is not in the devrank table.

        • tier string | null required

          The upstream provider’s own coarse label for `crackedScore` (for example "Elite"). The label set is the provider’s and is not a Vamo-stable vocabulary — treat it as display text and branch on `crackedScore` if you need a threshold. Null when the developer is not in the devrank table.

          max 200 chars
      • repos array of object required

        The developer’s top ATTRIBUTED public repositories — owned or authored-into, forks excluded — stars descending, capped at 12. This is a sample of their best work, not a complete repository list, and it is not an answer to "why did this person match my query" — read `evidence.matchedRepos` for that.

        max 12 items
        • name string required

          The repository name alone, without the owner (`linux`).

          max 200 chars
        • fullName string required

          GitHub `owner/name`. This is the join key: an evidence repo and a profile repo describing the same repository carry the same `fullName`.

          max 200 chars
        • description string | null required

          The repository's own GitHub description, verbatim. Null when it has none.

          max 5000 chars
        • language string | null required

          GitHub's primary language for the repository. Null when GitHub reports none (an empty or docs-only repo); never inferred from the code.

          max 200 chars
        • stars integer required

          Stargazer count at the time this profile was snapshotted, not at request time.

          min 0, max 100000000
        • commits integer

          How many commits THIS developer authored to this repository over the trailing year. This is the difference between a project they wrote and a project they landed one drive-by fix in — a 385k-star repository with 4 of their commits is not their work. Absent when no commit signal was captured; 0 means none in the trailing year, which for older dormant work is not the same as none ever.

          min 0, max 100000000
        • owned boolean

          True when the repository sits under the developer's own account, false when it is someone else's (an organisation's or another person's) and they are a contributor to it. This is the difference between "they built this" and "they committed to this", and it is the ONLY honest basis for crediting a repository's stars to a person. Absent when no ownership signal was captured; treat absent as unknown, never as false.

        • url string required

          The public github.com URL of the repository.

          max 2048 chars
      • languages array of string required

        Distinct primary languages across the developer’s repositories, at most 8. Presence means they have shipped public code in it; the list is not ranked by proficiency and carries no line counts.

        max 8 items
      • experience array of object required

        Employment history from the LinkedIn overlay, newest first. Empty for any developer we hold no LinkedIn match for, which is most of them.

        max 25 items
        • title string | null

          Job title, on an experience entry.

          max 200 chars
        • company string | null

          Employer name, on an experience entry.

          max 200 chars
        • school string | null

          Institution name, on an education entry.

          max 200 chars
        • degree string | null

          Degree awarded, on an education entry.

          max 200 chars
        • fieldOfStudy string | null

          Field of study, on an education entry.

          max 200 chars
        • startDate string | null

          Start date exactly as the source rendered it. Free text, NOT a normalised date: expect "2019", "Jan 2019" and "2019-01" from different records. Parse defensively.

          max 200 chars
        • endDate string | null

          End date in the same unnormalised free-text form as `startDate`. Absent or null on a current role.

          max 200 chars
        • current boolean | null

          The source's own "still there" flag. Set on experience entries; null on education entries.

      • education array of object required

        Education history from the LinkedIn overlay. Empty for any developer we hold no LinkedIn match for.

        max 25 items
        • title string | null

          Job title, on an experience entry.

          max 200 chars
        • company string | null

          Employer name, on an experience entry.

          max 200 chars
        • school string | null

          Institution name, on an education entry.

          max 200 chars
        • degree string | null

          Degree awarded, on an education entry.

          max 200 chars
        • fieldOfStudy string | null

          Field of study, on an education entry.

          max 200 chars
        • startDate string | null

          Start date exactly as the source rendered it. Free text, NOT a normalised date: expect "2019", "Jan 2019" and "2019-01" from different records. Parse defensively.

          max 200 chars
        • endDate string | null

          End date in the same unnormalised free-text form as `startDate`. Absent or null on a current role.

          max 200 chars
        • current boolean | null

          The source's own "still there" flag. Set on experience entries; null on education entries.

      • professional object | null

        LinkedIn-sourced professional scalars, present only when we hold a LinkedIn match for this developer. Absent or null for the majority of developers, which says nothing about their employment — only that we hold no overlay.

        • headline string | null required

          The LinkedIn headline, verbatim.

          max 5000 chars
        • title string | null required

          Current job title per LinkedIn, e.g. "Chief Technology Officer".

          max 200 chars
        • company string | null required

          Current employer per LinkedIn. Distinct from the GitHub-sourced `organization` field, and the two disagree often — LinkedIn is usually the fresher of the two.

          max 200 chars
        • seniority string | null required

          A coarse seniority label from the LinkedIn overlay ("c-level", "senior", …). Free text from the source, not a Vamo enum; do not switch on the exact string.

          max 200 chars
        • expertise array of string required

          Self-declared skill tags from the LinkedIn profile. Claimed, not demonstrated — the demonstrated equivalent is the repositories under `repos` and `evidence`.

          max 25 items
    • score number | null required

      The PAGE-LOCAL ordering key this page was sorted by, descending. It is NOT match quality and must not be shown or thresholded as one — read `relevance` for that. It is comparable only within this page: two rows from different pages, rounds, or queries cannot be compared, and the same developer can score differently on two runs. Most of the composite is about the developer regardless of your query (owns any repo, star band, whether a LinkedIn profile and devrank exist, contribution volume when the activity gate ran, minus a flat penalty for trophy accounts). A nonsense query that returns five people still scores them, so a high score means "the best of what came back", never "this matches what you asked for". Read `evidence.matchStatus` for query attribution. Null only when the producer did not rank (an older cached page).

    • relevance number | null

      THE PROVIDER’S OWN QUERY-MATCH RELEVANCE — the number to build a quality gate on, and the one `score` is not. It is the search index’s score for this row against this query. READ IT WITH the response’s `relevanceOrder`, which says whether higher or lower is better on this page: the direction INVERTS by lane, because the User lane has no vector and ranks by weighted BM25 (unbounded, higher is better) while the LinkedIn lane ranks by cosine distance (0..1, lower is better). It is comparable BETWEEN ROWS OF ONE QUERY, which is exactly what a threshold-based gate needs, and NOT across queries — BM25 magnitude moves with term rarity and with how many fields matched, so a rare token in a nonsense query can still score high on the one row containing it. Threshold on a fraction of the best row rather than an absolute constant. On the repo→contributor fanout lane it is the best-matching repo you built, which is that lane’s whole thesis for why you match. Null only when the lane that answered has no query to be relevant to at all: the repo seed gate, and any filter-only search, where the index ordered by recency instead of by match.

    • evidence object

      The proof-of-work and query-attribution block for this developer. Populated on every result from a live search; absent on pages served from an older cache.

      • status string required

        Whether we could assemble proof of work for this developer at all. `attached` = `topRepos` is populated. `partial` = some of it was assembled. `missing` = none was, and `reason` says why. A `missing` block is always explicit; an empty evidence block is never returned silently.

        attachedpartialmissing
      • reason string | null required

        Why the proof-of-work block is not fully `attached`. `no_owned_repos` = this developer owns no public repositories. `not_hydrated` = we did not fetch their repositories on this call. `enrichment_failed` = the fetch was attempted and failed. Null when `status` is `attached`.

        enrichment_failedno_owned_reposnot_hydrated
      • matchStatus string

        Whether `matchedRepos` genuinely answers "why did this person come back for my query". `attributed` = it does, and every entry carries a `via`. `unattributed` = the lane that produced this result cannot attribute repositories to the query, `matchedRepos` is empty, and you MUST NOT present `topRepos` to a user as if it were the reason they matched. Absent means `unattributed`.

        attributedunattributed
      • matchedRepos array of object required

        The repositories that connect this developer to your query. Empty whenever `matchStatus` is `unattributed`; non-empty whenever it is `attributed`.

        max 12 items
        • fullName string required

          GitHub `owner/name`. The join key onto `developer.repos[].fullName`, so you can match an evidence repo back to the profile repo it refers to.

          max 160 chars
        • stars integer required

          Stargazer count at retrieval time. 0 also means "the source returned no count", so do not read 0 as proof the repo is unstarred.

          min 0, max 100000000
        • language string | null

          GitHub’s primary language for the repository. Null when none was returned; never inferred from the code. Absent on pages produced before this field existed.

          max 200 chars
        • role string | null

          This person’s relationship to the repository, and it is deliberately conservative. `owner` means the repository sits under THEIR namespace. `contributor` means everything else, including the person who wrote most of the code in someone else’s or an organisation’s repository — a top committer on a company repo is a `contributor`, so do not read `contributor` as "minor" or `owner` as "wrote it". Null means the lane that produced this row genuinely cannot tell; absent means an older producer did not emit the field.

          ownercontributor
        • via string

          How this repository entered the evidence block, i.e. its PROVENANCE. It is NOT a statement about which of your search terms matched. `semantic` = the prose repo search returned it for the query. `seed` = you named this repository yourself (`levers.github.similarRepos` in exact mode, or `contributedRepos`) and this person commits to it. `owned` = it is one of their top owned repositories, included as background — `owned` appears only in `topRepos` and never in `matchedRepos`. Treat an unrecognised value as unknown provenance; new members may be added.

          semanticseedowned
        • similarity number | null

          How closely THIS repository matched the query, as a cosine DISTANCE: LOWER IS CLOSER, and it is comparable between the matched repos of one result rather than across queries. Populated only on the repo→contributor fanout, where the query matched the repository and the index scores it (`via: "semantic"`). Null everywhere else — the repo-seed gate has no query to be close to, and a repo the index scored nothing for reports null rather than a synthesized number. It is NOT the developer's relevance; read `results[].relevance` with `relevanceOrder` for that.

        • why string | null

          Reserved and always null. Retained for wire compatibility during a rollout; do not read it.

          max 5000 chars
      • topRepos array of object required

        The developer’s strongest owned repositories, as background proof of work. These are NOT query matches — a repository here says the person builds, not that they build what you asked for.

        max 12 items
        • fullName string required

          GitHub `owner/name`. The join key onto `developer.repos[].fullName`, so you can match an evidence repo back to the profile repo it refers to.

          max 160 chars
        • stars integer required

          Stargazer count at retrieval time. 0 also means "the source returned no count", so do not read 0 as proof the repo is unstarred.

          min 0, max 100000000
        • language string | null

          GitHub’s primary language for the repository. Null when none was returned; never inferred from the code. Absent on pages produced before this field existed.

          max 200 chars
        • role string | null

          This person’s relationship to the repository, and it is deliberately conservative. `owner` means the repository sits under THEIR namespace. `contributor` means everything else, including the person who wrote most of the code in someone else’s or an organisation’s repository — a top committer on a company repo is a `contributor`, so do not read `contributor` as "minor" or `owner` as "wrote it". Null means the lane that produced this row genuinely cannot tell; absent means an older producer did not emit the field.

          ownercontributor
        • via string

          How this repository entered the evidence block, i.e. its PROVENANCE. It is NOT a statement about which of your search terms matched. `semantic` = the prose repo search returned it for the query. `seed` = you named this repository yourself (`levers.github.similarRepos` in exact mode, or `contributedRepos`) and this person commits to it. `owned` = it is one of their top owned repositories, included as background — `owned` appears only in `topRepos` and never in `matchedRepos`. Treat an unrecognised value as unknown provenance; new members may be added.

          semanticseedowned
        • similarity number | null

          How closely THIS repository matched the query, as a cosine DISTANCE: LOWER IS CLOSER, and it is comparable between the matched repos of one result rather than across queries. Populated only on the repo→contributor fanout, where the query matched the repository and the index scores it (`via: "semantic"`). Null everywhere else — the repo-seed gate has no query to be close to, and a repo the index scored nothing for reports null rather than a synthesized number. It is NOT the developer's relevance; read `results[].relevance` with `relevanceOrder` for that.

        • why string | null

          Reserved and always null. Retained for wire compatibility during a rollout; do not read it.

          max 5000 chars
    • relationship DeveloperRelationship required

      What YOUR account already has on this developer: whether they are saved as a contact, on a shortlist, hidden, or already in outreach. Computed per account, so the same developer carries a different relationship for a different customer.

      • inContacts boolean required

        True when your account already holds this developer as a contact, hidden ones included.

      • projects integer required

        How many live projects this contact is a candidate of.

      • sequences integer

        How many ACTIVE outreach sequences this contact is in: not yet replied, not past the final step. A finished sequence does not count. Absent under the withholding rule described on this object.

      • doNotContactAt string | null required

        When this contact was marked do-not-contact, as an ISO 8601 instant. Non-null means outreach to them is suppressed. Null when they are contactable or not a contact at all.

      • lastContactedAt string | null

        When outreach last reached them. Null means never; absent means withheld.

      • touchCount integer

        How many outreach touches they have received. Absent means withheld.

      • projectNames array of string required

        Names of the projects they are a candidate of, for display.

      • sequenceNames array of string

        Names of the active sequences they are in. Absent means withheld.

      • addedAt string | null required

        When they became a contact, as an ISO 8601 instant. Null when they are not a contact.

      • addedBy string | null required

        Who added them: a member id, or an API key id when an agent did. Null when they are not a contact.

      • addedByEmail string | null required

        `addedBy` resolved for display: a member’s email address, the literal "API key", or the raw id when neither resolves.

    • facets array of object required

      The enrichment cells resolved for this developer on this call, one per applied facet. Empty when no enrichment applied. Each cell carries its own status: a cell is only usable when its status is `ok`.

      • developerId string required

        The developer this cell is about.

        max 64 chars
      • facetKey string required

        Which facet this cell answers.

        id.coreprofile.basicscore.crackedgithub.gardentags.matchedsignals.archetypesignals.signature_techsignals.builder_scopescore.gemsignals.ai_usagesignals.commit_factsactivity.contributionssignals.coreai.repo_summariesai.person_summaryidentity.linkedincontact.socialscontact.emailsfit.match_rationalefit.score_vs_jddossier.coredossier.contextualdossier.pitch_sheet
      • status string required

        The outcome for this one (developer × facet) pair. Exactly one status is billed: `ok`. `ok` = delivered, `value` is populated, and you were charged for it (or you already owned it). `pending` = a background job is computing it; poll the report until it settles. Not charged now; the charge is settled by the job. `unavailable` = we ran and there is genuinely nothing to return for this developer, including the case where the source answered with an empty result. Not charged. `failed` = the attempt errored. Not charged, and never retried inside the same report. `report_required` = this facet needs background compute and you asked on a synchronous endpoint that does not dispatch jobs. Not charged; request it via `POST /v1/developers/reports` to get it. Treat every status other than `ok` as "no data", not as a value.

        okpendingunavailablefailedreport_required
      • value object

        The facet payload. Present only when `status` is `ok`; its shape is specific to the facet key, so read it against the facet you asked for. A cell whose payload came back with nothing in it is downgraded to `unavailable` rather than returned as an empty `ok`, so an `ok` cell always carries at least one real field.

      • jobId string

        The background compute job producing this cell. Present only when `status` is `pending`.

  • cursor string | null required

    Opaque continuation token: pass it back as `cursor` for the next page. Null means the engine has no continuation left for this query. Do not parse it or construct one.

    max 256 chars
  • provider string required

    Which upstream index served this page. Provenance for debugging; do not branch on it.

    bountylab
  • cached boolean required

    True when this page was served from a cached result set rather than a fresh engine run. A cached page can be missing the newer envelope fields and can carry `evidence.matchStatus: unattributed`. Caching does not change what you are charged: search is billed per developer returned either way.

  • entity string

    Which index this query was actually routed to, after auto-routing. `User` = the GitHub developer index. `Repo` = repositories were searched and their contributors returned. `LinkedInUser` = the LinkedIn overlay, which covers only the minority of developers we hold a match for, so a query routed here reaches a much smaller population. The routing decides which levers can bind at all: pin `config.entity` and re-run if a lever you need landed in `unsupported`.

    UserRepoLinkedInUser
  • unsupported array of object

    Every lever you set that this lane could NOT apply as a hard filter. These are declared, never silently dropped — if a lever is listed here, the results were not filtered by it, so check this array before trusting a result set to satisfy a constraint. Each entry names a `route` that does serve the lever.

    max 50 items
    • lever string required

      The lever key that could not be applied, in the same dotted form you set it (`levers.github.contributedRepos`).

      max 5000 chars
    • tier one of

      How this lever can be served at best. `1` = it is a real push-down filter on some lane. `2` = it can only re-rank or annotate, never hard-filter. `3` = it is only available on the asynchronous deep lane.

    • reason string

      Plain-language explanation of why this lever did not bind on this run.

      max 5000 chars
    • route string

      The API path that DOES serve this lever, so the hint is directly actionable: `/v1/search/jobs` for the asynchronous deep lane, or `/v1/searches/execute` when another entity binds it (pin `config.entity` and re-run).

      max 200 chars
  • appliedLevers array of string

    The levers that DID bind on this page, by lever key. This is the other half of `unsupported`: every lever you set appears in exactly one of the two arrays, so you can tell a page that honoured all your constraints from one that honoured none — both otherwise look like a plausible list of developers.

    max 50 items
  • rankScope string

    What population the ordering was computed over. `page` means only the returned rows were ranked against each other, so `score` is a within-page ordering and paging further can surface a better candidate than anything on page one. `index` would mean ranking ran index-wide. Today this is always `page`.

    indexpage
  • relevanceOrder string | null

    How to read `results[].relevance` on THIS page, because the direction inverts by lane and assuming one silently reads the worst matches as the best. `higher_is_better` on the User lane, which has no vector and ranks by weighted BM25. `lower_is_better` on the two VECTOR lanes — the LinkedIn profile lane and the repo→contributor fanout — which report cosine distance. Null when the page carries no relevance to order at all: the repo seed gate has no query to be relevant to, and a filter-only search was ordered by recency rather than by match, so every row carries the same relevance — which must not be read as "everything matched equally".

    higher_is_betterlower_is_better
  • countStatus one of

    Whether you got the number of results you asked for, and if not, why. Never padded and never silently short.

  • searchConfig one of required

    The config that actually ran, fully resolved. When you executed a saved search this is what was stored; when you sent a V1 config this is the upgraded form. Read it to see the defaults that were filled in for you.

  • enrichment ExecuteSearchEnrichment

    The inline enrichment applied to this page and its itemised bill. Absent when no facet applied.

    • facets array of string required

      Every facet key actually applied to this page, after bundle macros and dependencies were expanded.

    • source string required

      Where the applied facets came from. `request` = this call named them. `account_default` = they were inherited from `/v1/me/preferences.defaultFacets`, which is why the same request body can cost different amounts on two accounts. Send `facets: []` to suppress the defaults.

      requestaccount_default
    • plan object required

      What you named versus what the dependency graph added and charged on top.

      • requested array of string required

        The facet keys you asked for, with any bundle macro expanded into its members.

      • added array of string required

        Facets that were resolved and CHARGED on top because a facet you requested cannot be computed without them. This is why a bill can exceed the price of the keys you named.

    • billing object required

      The itemised bill for this call. Reconcile on `billing.totalCredits`.

      • items array of object required

        One line per (developer × facet) cell, including the ones that cost nothing.

        • developerId string required

          The developer this line item is for.

          max 64 chars
        • facetKey string required

          The facet this line item is for.

          id.coreprofile.basicscore.crackedgithub.gardentags.matchedsignals.archetypesignals.signature_techsignals.builder_scopescore.gemsignals.ai_usagesignals.commit_factsactivity.contributionssignals.coreai.repo_summariesai.person_summaryidentity.linkedincontact.socialscontact.emailsfit.match_rationalefit.score_vs_jddossier.coredossier.contextualdossier.pitch_sheet
        • credits integer required

          Credits charged for this one cell. Zero unless `state` is `billed`.

          min 0
        • state string required

          `billed` = charged on this call. `owned` = you had already paid for this cell and it is still within its cache window, so it cost 0 and you still get the value. `included` = a sibling key of the same SKU carried this call's charge, so this cell cost 0 and is fully yours: you buy the SKU, not the key. `not_billed` = the cell did not resolve (failed, unavailable, or report_required), so it cost 0 and you got nothing. A failed cell can never be reported as billed.

          ownedbilledincludednot_billed
      • total integer required

        The sum of `items`, so FACET CELLS ONLY. This is NOT what the call cost — it excludes the route’s own charge. Reconciling a finance integration on this field under-reports every bill. Use `totalCredits`.

        min 0
      • baseCredits integer required

        The route’s own charge, separate from enrichment: one credit per developer returned on a search, one per input resolved on a lookup, 0 on a route that is free.

        min 0
      • totalCredits integer required

        What this call actually cost you: `baseCredits + total`. This is the number that matches the `x-cost` response header and the ledger entry. Reconcile on this.

        min 0
• 401 No or invalid credential
  • code string required

    Stable machine-readable error code. Branch on this, never on the numeric status.

    bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
  • message string required

    Human-readable explanation of the refusal.

  • status integer required

    The HTTP status code, repeated in the body.

  • remedy object

    A self-serve path forward, when one exists (a 402 points at the credit top-up).

    • kind string required

      What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

      topupconnect_mailbox
    • url string required

      Where to go to clear the condition: an API path, or a web app page when only a person can.

• 403 Missing search:read
  • code string required

    Stable machine-readable error code. Branch on this, never on the numeric status.

    bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
  • message string required

    Human-readable explanation of the refusal.

  • status integer required

    The HTTP status code, repeated in the body.

  • remedy object

    A self-serve path forward, when one exists (a 402 points at the credit top-up).

    • kind string required

      What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

      topupconnect_mailbox
    • url string required

      Where to go to clear the condition: an API path, or a web app page when only a person can.

• 404 No such saved search in this account
  • code string required

    Stable machine-readable error code. Branch on this, never on the numeric status.

    bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
  • message string required

    Human-readable explanation of the refusal.

  • status integer required

    The HTTP status code, repeated in the body.

  • remedy object

    A self-serve path forward, when one exists (a 402 points at the credit top-up).

    • kind string required

      What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

      topupconnect_mailbox
    • url string required

      Where to go to clear the condition: an API path, or a web app page when only a person can.

• 422 The saved search config is not executable
  • code string required

    Stable machine-readable error code. Branch on this, never on the numeric status.

    bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
  • message string required

    Human-readable explanation of the refusal.

  • status integer required

    The HTTP status code, repeated in the body.

  • remedy object

    A self-serve path forward, when one exists (a 402 points at the credit top-up).

    • kind string required

      What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

      topupconnect_mailbox
    • url string required

      Where to go to clear the condition: an API path, or a web app page when only a person can.