---
title: "Poll a sourcing brief"
method: GET
path: "/v1/briefs/{briefId}"
---

# Poll a sourcing brief

`GET /v1/briefs/{briefId}`

## Request

- Base URL: `https://api.githunt.ai`
- URL: `https://api.githunt.ai/v1/briefs/{briefId}`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Returns the brief's status and progress while it runs, and the full result once it is `complete` or `partial`. `partial` means the whole brief did not run: a ceiling was hit (search calls or time budget), a batch held more ranked rows than the run could read (`coverage.truncated`), or evidence was still building. Report the regions actually covered rather than claiming exhaustive coverage. Debits 0 monthly credits; every call still passes the daily cap. Only the account that submitted the brief can read it; anyone else gets the same `404` as a brief that does not exist.

## Path parameters

- `briefId` string, uuid, required

## Response `200`

Brief status. Carries `result` when `status` is `complete` or `partial`, and `retry_after_seconds` while it is still running.

- BriefStatusResponse
  - `success` true
  - `data` object
    - `brief_id` string, uuid
    - `status` 'queued' | 'running' | 'complete' | 'partial' | 'failed'
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `progress` object: Live counters while the run is in flight.
      - `phase` 'queued' | 'search' | 'evidence' | 'done' | 'failed'
      - `searches_done` integer
      - `searches_planned` integer
      - `candidates` integer
      - `shortlisted` integer
      - `evidence_ready` integer
      - `evidence_pending` integer
    - `retry_after_seconds` integer: Present while the brief is still running.
    - `error` string: Present when `status` is `failed`.
    - `result` BriefResult: Present once the brief is `complete` or `partial`.
      - `cover` object: The brief as run, plus the assumptions every claim below rests on.
        - `brief_id` string
        - `prepared_at` string, date-time
        - `criteria` object
        - `geography` object
        - `assumptions` string[]
        - `delivered` integer
        - `screening_leads` integer
        - `requested_profiles` integer
      - `summary` object[]: One row per delivered profile, in delivery order.
        - `rank` integer
        - `login` string
        - `name` string, nullable
        - `location` string, nullable
        - `utc_offset` object, nullable
        - `last_skill_commit` string, nullable
        - `inspected_in_window` integer
        - `domain_tier` 'core' | 'adjacent' | 'generic' | 'none'
        - `tenure_status` string
        - `screening_questions` integer
        - `recency` number, nullable: The recency multiplier from `rank_breakdown`.
        - `org` number, nullable
        - `domain` number, nullable
      - `profiles` BriefCard[]
        - `login` string
        - `name` string, nullable
        - `location` string, nullable
        - `location_resolution` object, nullable: How the stated base resolved at the run timestamp. Only `resolved` can be delivered; `ambiguous` and `unresolved` are screening leads.
          - `status` 'resolved' | 'ambiguous' | 'unresolved'
          - `country` string, nullable
          - `utc_offset` object, nullable
          - `basis` string, nullable
          - `screening_reason` string, nullable
          - `observed_at` string
        - `company` string, nullable
        - `bio` string, nullable
        - `hireable` unknown
        - `profile_url` string
        - `score` number, nullable
        - `rank_breakdown` object, nullable: Why the ranker placed this row where it did. Present when the brief named languages, skills, sectors, organizations or domains.
          - `base` number: Score before the evidence multipliers.
          - `recency` number
          - `org` number
          - `domain` number
          - `final` number: The value the ordering actually used.
        - `discovered_by` string[]: Which location batches surfaced this candidate.
        - `evidence_status` 'cached' | 'built' | 'pending' | 'skipped'
        - `evaluated_at` string, nullable
        - `window` object, nullable
        - `coverage` object, nullable: The evidence scan's own coverage, as on the evidence endpoint.
        - `criteria` object, nullable: The evidence report's criterion assessments, verbatim.
        - `skill_evidence` object
          - `status` string
          - `reason` string, nullable
          - `inspected_in_window` integer: Inspected candidate-authored in-window commits in a requested skill. One or more is what makes a card deliverable.
          - `last_commit` string, nullable
          - `repos` object[]
            - `repository` string
            - `url` string
            - `owner_type` string, nullable
            - `commits_seen` integer
            - `commits_in_window` integer
            - `inspected` integer
            - `last_commit` string, nullable
          - `commits` object[]
            - `url` string, nullable
            - `date` string, nullable
            - `message` string, nullable
            - `repository` string, nullable
            - `files_changed` integer, nullable
            - `code_languages` string[]
        - `commercial_signals` object: Public context for paid work, never a tenure claim. `tenure_status` is `unknown` unless a dated, corroborated interval exists.
          - `public_signals_only` true
          - `tenure_status` string
          - `tenure_reason` string, nullable
          - `items` object[]
            - `type` 'public_org_contribution' | 'self_reported_employment' | 'commit_email_domain'
            - `value` string
            - `url` string, nullable
            - `organization` string, nullable
            - `company` string, nullable
            - `interval` object, nullable
            - `commits` integer, nullable
            - `active_years` integer[]
            - `languages` string[]
        - `domain_evidence` object
          - `tier` 'core' | 'adjacent' | 'generic' | 'none': `core` only when the evidence report's `core_domain_recent` criterion is supported. A core term in a README or a commit subject is context and lands as `adjacent` at best.
          - `status` string
          - `reason` string, nullable
          - `subsystems` string[]
          - `items` object[]
            - `url` string, nullable
            - `date` string, nullable
            - `term` string
            - `pack` string
            - `subsystem` string, nullable
            - `context` string, nullable
            - `kind` string
            - `repository` string, nullable
        - `screening_questions` string[]
        - `links` object
          - `profile` string
          - `blog` string
          - `twitter` string
      - `screening_leads` object[]: Cards that did not meet a delivery rule, each with a `reason`. Overflow beyond `maxProfiles` appears here too.
        - `login` string
        - `name` string, nullable
        - `location` string, nullable
        - `location_resolution` object, nullable: How the stated base resolved at the run timestamp. Only `resolved` can be delivered; `ambiguous` and `unresolved` are screening leads.
          - `status` 'resolved' | 'ambiguous' | 'unresolved'
          - `country` string, nullable
          - `utc_offset` object, nullable
          - `basis` string, nullable
          - `screening_reason` string, nullable
          - `observed_at` string
        - `company` string, nullable
        - `bio` string, nullable
        - `hireable` unknown
        - `profile_url` string
        - `score` number, nullable
        - `rank_breakdown` object, nullable: Why the ranker placed this row where it did. Present when the brief named languages, skills, sectors, organizations or domains.
          - `base` number: Score before the evidence multipliers.
          - `recency` number
          - `org` number
          - `domain` number
          - `final` number: The value the ordering actually used.
        - `discovered_by` string[]: Which location batches surfaced this candidate.
        - `evidence_status` 'cached' | 'built' | 'pending' | 'skipped'
        - `evaluated_at` string, nullable
        - `window` object, nullable
        - `coverage` object, nullable: The evidence scan's own coverage, as on the evidence endpoint.
        - `criteria` object, nullable: The evidence report's criterion assessments, verbatim.
        - `skill_evidence` object
          - `status` string
          - `reason` string, nullable
          - `inspected_in_window` integer: Inspected candidate-authored in-window commits in a requested skill. One or more is what makes a card deliverable.
          - `last_commit` string, nullable
          - `repos` object[]
            - `repository` string
            - `url` string
            - `owner_type` string, nullable
            - `commits_seen` integer
            - `commits_in_window` integer
            - `inspected` integer
            - `last_commit` string, nullable
          - `commits` object[]
            - `url` string, nullable
            - `date` string, nullable
            - `message` string, nullable
            - `repository` string, nullable
            - `files_changed` integer, nullable
            - `code_languages` string[]
        - `commercial_signals` object: Public context for paid work, never a tenure claim. `tenure_status` is `unknown` unless a dated, corroborated interval exists.
          - `public_signals_only` true
          - `tenure_status` string
          - `tenure_reason` string, nullable
          - `items` object[]
            - `type` 'public_org_contribution' | 'self_reported_employment' | 'commit_email_domain'
            - `value` string
            - `url` string, nullable
            - `organization` string, nullable
            - `company` string, nullable
            - `interval` object, nullable
            - `commits` integer, nullable
            - `active_years` integer[]
            - `languages` string[]
        - `domain_evidence` object
          - `tier` 'core' | 'adjacent' | 'generic' | 'none': `core` only when the evidence report's `core_domain_recent` criterion is supported. A core term in a README or a commit subject is context and lands as `adjacent` at best.
          - `status` string
          - `reason` string, nullable
          - `subsystems` string[]
          - `items` object[]
            - `url` string, nullable
            - `date` string, nullable
            - `term` string
            - `pack` string
            - `subsystem` string, nullable
            - `context` string, nullable
            - `kind` string
            - `repository` string, nullable
        - `screening_questions` string[]
        - `links` object
          - `profile` string
          - `blog` string
          - `twitter` string
        - `reason` string
      - `coverage` object: What was actually searched. Never a claim of worldwide coverage.
        - `regions_requested` string[]
        - `countries_searched` string[]
        - `countries_skipped` object[]: Countries the region expansion produced that the brief would have discarded anyway, so no search was spent on them.
          - `country` string
          - `reason` 'excluded_location' | 'utc_offset_band': `excluded_location` - named in `excludeLocations`. `utc_offset_band` - the country's whole UTC range sits inside `excludeUtcOffsets` at the run timestamp. A country only partly inside the band is still searched.
        - `batches_planned` integer
        - `batches_run` integer
        - `search_calls` integer
        - `candidate_rows` integer: Rows returned before dedup, the denominator for a duplicate rate.
        - `unique_candidates` integer
        - `shortlisted` integer
        - `evidence` object
          - `cached` integer
          - `built` integer
          - `pending` integer
          - `skipped` integer
        - `truncated` boolean: A batch's ranking held more rows than the run could read, so some ranked candidates were never seen.
        - `retrieval_capped` boolean: True when the ranker's per-location retrieval ceiling was reached for at least one country: more candidates may exist there than this run could read. A capped read is not an incomplete run - absence under a cap is not evidence of absence - and it does not by itself make `status` `partial`.
        - `partial` boolean: True when a ceiling was hit, a batch was truncated, or evidence was still building. `status` is `partial` exactly when this is. A per-location retrieval cap is reported separately as `retrieval_capped`.
        - `stopped_reason` 'search_call_ceiling' | 'time_budget' | 'null', nullable
        - `batches` object[]
        - `note` string
      - `manifest` object: Everything needed to reproduce or compare two runs.
        - `brief_id` string
        - `run_started_at` string, date-time
        - `run_completed_at` string, date-time
        - `skills` string[]
        - `domains` string[]
        - `evidence_requested` boolean
        - `evidence_cache_key` string, nullable
        - `evidence_schema_version` integer
        - `inspection_rules_version` integer
        - `ceilings` object
  - `meta` Meta: Envelope metadata. `quota.cost` is 0 on endpoints that debit no credits.
    - `requestId` string
    - `quota` Quota
      - `used` integer
      - `limit` integer: -1 means unlimited
      - `month` string
      - `cost` integer: Credits this request debited (search: 1, get user: 1, evidence report: 3 when a report is returned and 0 while pending, analyze profile: 3, list operations: 0). `used` already reflects this charge.
      - `rollover` integer: Unused credits banked from the previous month and available on top of `limit` this month (`remaining` = limit + rollover - used). Only present on the Team plan, capped at one extra month's allowance (so at most 2x the allowance is usable in a month).

## Other responses

- `400`: Invalid request
- `401`: Missing, invalid, or revoked API key
- `404`: No matching developer
- `429`: Monthly or daily quota exceeded
- `500`: Unexpected server error

---

[API](https://skmtc.dev/githunt/apis/githunt-api.md) · [All operations](https://skmtc.dev/githunt/apis/githunt-api/llms.txt) · [OpenAPI document](https://skmtc.dev/githunt/apis/githunt-api/revisions/6fc325607da0?raw)