> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firmintent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List your jobs

> Your jobs, newest first, scoped to your key — a read utility (not part of the core 2-call flow).
`q` filters by the submitted input; `limit` (max 100) + `skip` paginate.



## OpenAPI

````yaml https://api.firmintent.com/openapi.json get /v1/jobs
openapi: 3.1.0
info:
  title: firmintent API
  description: >

    Give firmintent a **LinkedIn company and persona** — get back the **right
    people**.


    You submit a company — a **LinkedIn company URL** (`…/company/<slug-or-id>`)
    or a **bare numeric

    company id**; we scan and broadly enrich its roster, find likely persona
    candidates, verify the

    shortlist, and return a ranked target list. (Bare name/domain lookup is a
    later layer — not accepted

    yet.) Jobs run

    **asynchronously** (minutes) — you either poll `GET /v1/jobs/{id}` or
    receive a **webhook**.


    All endpoints are versioned under **`/v1`**. Pin the version; new fields are
    added within `/v1`,

    breaking changes ship under a new `/vN`.


    ### Authentication

    Every request needs an API key in the `X-API-Key` header. Generate yours in
    the

    [dashboard](https://app.firmintent.com/dashboard). `POST /v1/jobs` spends
    money, so it

    is never anonymous.


    ### The flow — two calls

    1. `POST /v1/jobs` `{ "input": "linkedin.com/company/<slug>", "operation":
    "target_people", "persona": "owners-founders" }` → `202 { job_id }`

    2. Poll `GET /v1/jobs/{job_id}` until `status: "done"` — that response
    contains
       `target_people[]` inline. No third call.

    Re-polling a finished job returns the same result (idempotent, already paid
    for), so a lost response

    never costs a new job.


    ### Webhook (optional — instead of polling)

    Pass `callback_url` on `POST /v1/jobs`. When the job is done we `POST` that
    URL with the full result:

    `{ job_id, company_id, company, status: "done", target_people_count,
    target_people[] }`. You just need

    an HTTPS endpoint on your side that returns `2xx`.
  contact:
    name: firmintent
    url: https://firmintent.com/
  version: 1.0.0
servers:
  - url: https://api.firmintent.com
    description: Production
security: []
tags:
  - name: jobs
    description: Submit and track target-people jobs.
  - name: account
    description: Your credit balance, tier and usage.
  - name: personas
    description: Saved target audiences used by persona-first jobs.
paths:
  /v1/jobs:
    get:
      tags:
        - jobs
      summary: List your jobs
      description: >-
        Your jobs, newest first, scoped to your key — a read utility (not part
        of the core 2-call flow).

        `q` filters by the submitted input; `limit` (max 100) + `skip` paginate.
      operationId: list_jobs_v1_jobs_get
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            title: Limit
        - name: skip
          in: query
          required: false
          schema:
            type: integer
            default: 0
            title: Skip
        - name: q
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Q
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobList'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    JobList:
      properties:
        count:
          type: integer
          title: Count
          description: Total jobs matching the query (for pagination).
          examples:
            - 42
        jobs:
          items:
            $ref: '#/components/schemas/JobListItem'
          type: array
          title: Jobs
      type: object
      required:
        - count
        - jobs
      title: JobList
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
        - error
      title: ErrorResponse
      description: >-
        Every non-2xx response has this shape: a single `error` object.
        Consistent across all status codes.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    JobListItem:
      properties:
        job_id:
          type: string
          title: Job Id
        input:
          anyOf:
            - type: string
            - type: 'null'
          title: Input
          examples:
            - linkedin.com/company/anthropic
        operation:
          anyOf:
            - type: string
            - type: 'null'
          title: Operation
          examples:
            - target_people
        status:
          type: string
          enum:
            - processing
            - done
            - not_found
            - no_employees
            - no_people_found
            - too_large
            - failed
            - cancelled
          title: Status
          examples:
            - done
        company_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Company Id
          examples:
            - 3384253
        company_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Company Name
          description: The resolved company's name. Present once resolved.
          examples:
            - Anthropic
        company_logo:
          anyOf:
            - type: string
            - type: 'null'
          title: Company Logo
          description: The resolved company's logo URL, if any.
        persona:
          anyOf:
            - type: string
            - type: 'null'
          title: Persona
          description: >-
            The persona (target) this search used — present when one was
            applied.
          examples:
            - Owners & founders
        employees:
          anyOf:
            - type: integer
            - type: 'null'
          title: Employees
          description: The company's employee count (self-reported). Present once resolved.
          examples:
            - 320
        team_scanned:
          anyOf:
            - type: integer
            - type: 'null'
          title: Team Scanned
        target_people:
          anyOf:
            - type: integer
            - type: 'null'
          title: Target People
          description: Final persona matches.
          examples:
            - 5
        credits_charged:
          type: integer
          enum:
            - 0
            - 1
          title: Credits Charged
          description: Actual numeric charge for this job.
          default: 0
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
          description: ISO 8601 UTC.
          examples:
            - '2026-07-18T06:29:45Z'
      type: object
      required:
        - job_id
        - status
      title: JobListItem
    ErrorDetail:
      properties:
        code:
          type: string
          title: Code
          description: Stable machine-readable error code.
          examples:
            - insufficient_credits
        message:
          type: string
          title: Message
          description: Human-readable explanation.
          examples:
            - You're out of credits. Top up to run jobs.
        balance:
          anyOf:
            - type: integer
            - type: 'null'
          title: Balance
          description: Your current credit balance (present on credit errors).
        limit:
          anyOf:
            - type: integer
            - type: 'null'
          title: Limit
          description: Your plan's concurrency limit (present on concurrency errors).
      type: object
      required:
        - code
        - message
      title: ErrorDetail
      description: >-
        A single error. Branch on `code` (stable, machine-readable) — never on
        `message` (human text that

        may change). Extra fields carry context: `balance` on credit errors,
        `limit` on concurrency errors.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: Your brk_live_ API key.
      in: header
      name: X-API-Key

````