Request a developer enrichment report (async compute)

Request body DeveloperReportRequest

Responses

• 200 The report id plus the first cell snapshot and its itemised bill
  • reportId string required

    The durable id of this report. Poll `GET /v1/developers/reports/{reportId}` with it; retrieval is free and the report is shared by everyone on the account.

  • status string required

    `generating` = at least one cell is still being computed; poll again after `retryAfterMs`. `ready` = every cell has settled, which means each one reached `ok`, `unavailable` or `failed` — it does NOT mean every cell succeeded. Polling always terminates.

    generatingready
  • cells array of object required

    The first snapshot of the (developer × facet) grid. Compute cells typically start `pending`.

    • 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`.

  • pending boolean required

    True while any cell is still `pending`. The same fact as `status === "generating"`, as a boolean.

  • retryAfterMs integer | null required

    How long to wait before polling again, in milliseconds. Null once nothing is pending.

  • plan object required

    What you asked for versus what the dependency graph added and charged.

    • 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. Compute cells are charged up front here, which is what makes retrieval free; a job that fails refunds its cell.

    • 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
  • jobIds array of string required

    The distinct background jobs backing the pending cells, for tracing.

• 400 Empty/oversized arrays, an unknown facet, a misused contextRef, or no compute facet requested
  • 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.

• 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.

• 402 Insufficient credit balance
  • 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.

• 429 Per-actor rate limit exceeded
  • 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.