> ## Documentation index
> Fetch the complete index at: /llms.txt
> Use it to discover every page before exploring further.

# Queries

> Every read the API answers, in alphabetical order, with what each takes and returns, the scope it needs and an example to send.

### activeEngagement

`query`, returns [`Engagement`](/docs/types.md#engagement), any key

The engagement named by the X-Engagement-ID header. Null when the request acts as your own firm.

Example:

```graphql
{
  activeEngagement {
    id
    approvalRecorded
    authorisationRef
    authorisedOn
    effectiveFrom
    effectiveTo
    engagementId
    grantedBy
    client {
      id
      name
      kind
    }
    agent {
      id
      name
      kind
    }
  }
}
```

### amountOutstanding

`query`, returns [`OutstandingTotal!`](/docs/types.md#outstandingtotal), needs `BILL_READ`

What is still owed across the whole portfolio, and how complete that figure is.

Example:

```graphql
{
  amountOutstanding {
    installmentCount
    installmentsPaidPerRecords
    installmentsWithUnknownPayment
    known
    withheldCount
  }
}
```

### apiKeys

`query`, returns [`[ApiKey!]!`](/docs/types.md#apikey), signed-in people only

Your firm's API keys, the ones that work first. Always the firm's own, whichever client you are acting for. For people signed in to the app; a request made with a key is refused.

Example:

```graphql
{
  apiKeys {
    id
    name
    status
    createdAt
    expiresAt
    lastUsedAt
    prefix
    revokedAt
  }
}
```

### assessingJurisdictions

`query`, returns [`[Jurisdiction!]!`](/docs/types.md#jurisdiction), needs `PARCEL_READ`

The units that assess this portfolio's parcels, where its appeals are filed, by state then name.

Example:

```graphql
{
  assessingJurisdictions {
    id
    name
    assesses
    billDelivery
    bills
    fipsCode
    installmentsPerYear
    kind
  }
}
```

### bill

`query`, returns [`TaxBill`](/docs/types.md#taxbill), needs `BILL_READ`

The bill one of its installments belongs to. A bill has no id of its own, so pass the id of any of its installments. Null when the installment is not visible to you, which is also what one that does not exist returns.

Arguments:

- `id` (`ID!`, required): The id of one of the bill's installments.

Example:

```graphql
query ($id: ID!) {
  bill(id: $id) {
    key
    status
    annualTotal
    assessmentYear
    billNumber
    billType
    chargesTotal
    installmentsTotal
    acceptedAutomatically {
      at
      reason
    }
    amountOutstanding {
      installmentCount
      installmentsPaidPerRecords
      installmentsWithUnknownPayment
      known
      withheldCount
    }
  }
}
```

### billInbox

`query`, returns [`BillConnection!`](/docs/types.md#billconnection), needs `BILL_READ`

The bills waiting on a decision (NEEDS_REVIEW or DISPUTED), the oldest arrival first and the undated last; or, with view DECIDED, the ones a person accepted or rejected, newest arrival first with the undated ahead of them. One record per bill. Needs PARCEL_READ as well as BILL_READ. A cursor belongs to the filter it was cut under.

Arguments:

- `after` (`String`): The cursor to continue from: the endCursor of the page before.
- `before` (`String`): Not supported: lists page forward only, with first and after.
- `filter` ([`BillInboxFilter`](/docs/types.md#billinboxfilter)): Which bills. The waiting ones when omitted.
- `first` (`Int`): How many records to return: 25 when omitted, at most 100.
- `last` (`Int`): Not supported: lists page forward only, with first and after.

Example:

```graphql
{
  billInbox(first: 25) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        key
        status
        annualTotal
        assessmentYear
        billNumber
      }
    }
  }
}
```

### calendarFeeds

`query`, returns [`[CalendarFeed!]!`](/docs/types.md#calendarfeed), needs `PARCEL_READ`

The calendar feeds still in force over this portfolio, newest first. Revoked feeds are not listed.

Example:

```graphql
{
  calendarFeeds {
    id
    createdAt
    label
    lastFetchedAt
    revokedAt
    createdBy {
      id
      name
      email
    }
  }
}
```

### countiesInPortfolio

`query`, returns [`[CountyOutstanding!]!`](/docs/types.md#countyoutstanding), needs `PARCEL_READ`

Every unit that bills a parcel in the portfolio (a county, a township, a school district), with what is owed to each. Ordered by the amount owed, largest first, then by name. The rows are billing units of any level, under a name kept for compatibility.

Example:

```graphql
{
  countiesInPortfolio {
    parcelCount
    jurisdiction {
      id
      name
      assesses
      billDelivery
      bills
    }
  }
}
```

### coverage

`query`, returns [`Coverage!`](/docs/types.md#coverage), any key

Where bills can be fetched: by state and by county, with the reason where they cannot. The same for every caller.

Example:

```graphql
{
  coverage {
    countyTotals {
      assessmentOnly
      closed
      covered
      noPortal
      notSurveyed
    }
    totals {
      assessmentOnly
      closed
      covered
      noPortal
      notSurveyed
    }
  }
}
```

### coverageUnit

`query`, returns [`CoverageUnit`](/docs/types.md#coverageunit), any key

One unit by its code (US-CA-FIPS-06007), with its sites. Null when the registry does not hold it, and for a state.

Arguments:

- `unitCode` (`String!`, required): The unit code, as Jurisdiction.unitCode has it.

Example:

```graphql
query ($unitCode: String!) {
  coverageUnit(unitCode: $unitCode) {
    name
    status
    assesses
    bills
    countyLevel
    fips
    level
    state
    portals {
      status
      discoveredOn
      host
      reason
      url
    }
  }
}
```

### deadlineGeneration

`query`, returns [`DeadlineGeneration!`](/docs/types.md#deadlinegeneration), needs `PARCEL_READ`

When the dates deadlines returns were last worked out, and whether a change saved since is waiting on it. Asked in the same request as deadlines, it answers for the set that request read.

Example:

```graphql
{
  deadlineGeneration {
    generatedAt
    stale
  }
}
```

### deadlines

`query`, returns [`[Deadline!]!`](/docs/types.md#deadline), needs `PARCEL_READ`

Payment and appeal dates across the whole portfolio, soonest first. Dates that could not be worked out come last, with the reason, rather than being hidden. Give from and to for a large portfolio, which otherwise lists every date to come. A parcel with no bill yet has no appeal dates.

Arguments:

- `from` ([`Date`](/docs/types.md#date)): The first day to include. A date that could not be worked out is listed whatever the range.
- `to` ([`Date`](/docs/types.md#date)): The last day to include. A date that could not be worked out is listed whatever the range.

Example:

```graphql
{
  deadlines {
    id
    acknowledgedAt
    assessmentYear
    generatedAt
    kind
    on
    qualifier
    source
    parcel {
      id
      parcelNumber
      status
      useCode
    }
    jurisdiction {
      id
      name
      assesses
      billDelivery
      bills
    }
  }
}
```

### feedRuns

`query`, returns [`[FeedRun!]!`](/docs/types.md#feedrun), needs `BILL_READ`

The last nights of the feed for the client named by X-Engagement-ID, newest first. Empty without an engagement, or when no feed is set up for the firm.

Arguments:

- `last` (`Int`, default 7): How many nights: 7 when omitted.

Example:

```graphql
{
  feedRuns {
    id
    deliveredTo
    feedName
    finishedAt
    message
    outcome
    startedAt
  }
}
```

### inboxSummary

`query`, returns [`InboxSummary!`](/docs/types.md#inboxsummary), needs `BILL_READ`

The inbox in numbers: what arrived this week, what could not be read, and what waits. Needs PARCEL_READ as well as BILL_READ.

Example:

```graphql
{
  inboxSummary {
    beingChecked
    disputed
    failedExtractionsThisWeek
    needsReview
    receivedThisWeek
    withheld
  }
}
```

### ingestionStatus

`query`, returns [`[CountyIngestionStatus!]!`](/docs/types.md#countyingestionstatus), needs `BILL_READ`

What the nightly fetch did in each county the portfolio holds parcels in: which answered last night and which are failing. California counties only, for now. Needs PARCEL_READ as well as BILL_READ.

Example:

```graphql
{
  ingestionStatus {
    attempts24h
    failures24h
    lastAnsweredAt
    lastAttemptAt
    lastOutcome
    lastSuccessAt
    parcels
    streak
    jurisdiction {
      id
      name
      assesses
      billDelivery
      bills
    }
  }
}
```

### jurisdictions

`query`, returns [`[Jurisdiction!]!`](/docs/types.md#jurisdiction), any key

Taxing units from the registry, which is the same for every caller, in state and name order: filter by state, by level, or search by name; at least one is required. At most first are returned (500 when omitted, up to 5,000), so narrow by level or search where a state holds more. An empty list means no unit matched.

Arguments:

- `first` (`Int`): How many to return at most: 500 when omitted, up to 5,000.
- `level` (`String`): The kind of unit, as Jurisdiction.level has it: county, city, town, township, school_district and so on.
- `search` (`String`): Part of the name.
- `state` (`String`): A two-letter state code.

Example:

```graphql
{
  jurisdictions {
    id
    name
    assesses
    billDelivery
    bills
    fipsCode
    installmentsPerYear
    kind
  }
}
```

### legalEntities

`query`, returns [`[LegalEntity!]!`](/docs/types.md#legalentity), needs `PARCEL_READ`

The owners of record the portfolio holds parcels under, by name.

Example:

```graphql
{
  legalEntities {
    id
    name
    taxIdLast4
  }
}
```

### legalEntitiesInPortfolio

`query`, returns [`[LegalEntityHolding!]!`](/docs/types.md#legalentityholding), needs `PARCEL_READ`

Every legal entity that holds a parcel in the portfolio, with how many, their assessed value and what is owed on their bills: the breakdown by owner. Ordered by amount owed, then assessed value, then name. An entity with no parcel is not listed.

Example:

```graphql
{
  legalEntitiesInPortfolio {
    assessedValue
    assessedValueAsOf
    parcelCount
    legalEntity {
      id
      name
      taxIdLast4
    }
  }
}
```

### myEngagements

`query`, returns [`[Engagement!]!`](/docs/types.md#engagement), any key

Every client engagement your firm holds, the ones in force first. Lapsed engagements are listed too, so a client is not mistaken for a deleted one; a request under one is refused.

Example:

```graphql
{
  myEngagements {
    id
    approvalRecorded
    authorisationRef
    authorisedOn
    effectiveFrom
    effectiveTo
    engagementId
    grantedBy
    client {
      id
      name
      kind
    }
    agent {
      id
      name
      kind
    }
  }
}
```

### node

`query`, returns [`Node`](/docs/types.md#node), any key

One record by its id, whatever its type. Null with a FORBIDDEN error when your key lacks the scope its type needs; null alone when it is not visible to you or names nothing.

Arguments:

- `id` (`ID!`, required): The id, as any query returned it.

Example:

```graphql
query ($id: ID!) {
  node(id: $id) {
    __typename
    id
  }
}
```

### nodes

`query`, returns [`[Node]!`](/docs/types.md#node), any key

Several records by id, in the order asked, with null in the place of each that is not visible to you, and a FORBIDDEN error when your key lacks the scope a type needs.

Arguments:

- `ids` (`[ID!]!`, required): The ids, as any query returned them.

Example:

```graphql
query ($ids: [ID!]!) {
  nodes(ids: $ids) {
    __typename
    id
  }
}
```

### parcel

`query`, returns [`Parcel`](/docs/types.md#parcel), needs `PARCEL_READ`

One parcel: by id, or by parcel number within the unit that assesses it. Pass either id, or parcelNumber with jurisdictionId; anything else is BAD_USER_INPUT. Null when the parcel is not visible to you, which is also what a parcel that does not exist returns.

Arguments:

- `id` (`ID`): The parcel's id.
- `jurisdictionId` (`ID`): The id of the unit that assesses the parcel. With parcelNumber.
- `parcelNumber` (`String`): As the county writes it. With jurisdictionId.

Example:

```graphql
query ($id: ID) {
  parcel(id: $id) {
    id
    parcelNumber
    status
    useCode
    jurisdiction {
      id
      name
      assesses
      billDelivery
      bills
    }
    situsAddress {
      city
      county
      line1
      line2
      postalCode
    }
  }
}
```

### parcels

`query`, returns [`ParcelConnection!`](/docs/types.md#parcelconnection), needs `PARCEL_READ`

The parcels you can see, a page at a time: filter and order them, then page with first and after. A cursor belongs to the filter and order it was cut under.

Arguments:

- `after` (`String`): The cursor to continue from: the endCursor of the page before.
- `before` (`String`): Not supported: lists page forward only, with first and after.
- `filter` ([`ParcelFilter`](/docs/types.md#parcelfilter)): Which parcels. All of them when omitted.
- `first` (`Int`): How many records to return: 25 when omitted, at most 100.
- `last` (`Int`): Not supported: lists page forward only, with first and after.
- `orderBy` ([`ParcelOrder`](/docs/types.md#parcelorder)): How to order them. Assessed value, highest first, when omitted.

Example:

```graphql
{
  parcels(first: 25) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        parcelNumber
        status
        useCode
      }
    }
  }
}
```

### portfolioSummary

`query`, returns [`PortfolioSummary!`](/docs/types.md#portfoliosummary), needs `REPORT_READ`

The portfolio in numbers, as it stands now: parcels, the units that bill them, assessed value by state, and what the open appeals might save. Needs PARCEL_READ as well as REPORT_READ.

Example:

```graphql
{
  portfolioSummary {
    assessedValueAsOf
    jurisdictionCount
    parcelCount
    totalAssessedValue
    appealUpside {
      appealsWithoutRate
      basisDecidedAppeals
      modeled
      openAppeals
      realizedRatio
    }
    byState {
      assessedValue
      parcelCount
      state
    }
  }
}
```

### reportCatalog

`query`, returns [`[ReportCatalogEntry!]!`](/docs/types.md#reportcatalogentry), any key

The reports that can be produced, with their columns, in the order the app shows them. The same for every caller.

Example:

```graphql
{
  reportCatalog {
    name
    category
    columns
    description
    formats
    kind
    scopes
  }
}
```

### reportJob

`query`, returns [`ReportJob`](/docs/types.md#reportjob), needs `REPORT_READ`

One requested report, by id. Null when it is not visible to you.

Arguments:

- `id` (`ID!`, required): The report job's id, as requestReport returned it.

Example:

```graphql
query ($id: ID!) {
  reportJob(id: $id) {
    id
    name
    status
    byteSize
    downloadUrl
    error
    filterDescription
    finishedAt
    requestedBy {
      id
      name
      email
    }
  }
}
```

### reportJobs

`query`, returns [`[ReportJob!]!`](/docs/types.md#reportjob), needs `REPORT_READ`

Reports requested over this portfolio, newest first.

Arguments:

- `first` (`Int`, default 20): How many: 20 when omitted, at most 100.

Example:

```graphql
{
  reportJobs {
    id
    name
    status
    byteSize
    downloadUrl
    error
    filterDescription
    finishedAt
    requestedBy {
      id
      name
      email
    }
  }
}
```

### ruleReports

`query`, returns [`[RuleReport!]!`](/docs/types.md#rulereport), needs `PARCEL_READ`

The reports filed about rules from this portfolio, newest first, up to 100, with each one's status.

Example:

```graphql
{
  ruleReports {
    id
    status
    assessmentYear
    createdAt
    evidenceUrl
    problem
    resolution
    resolvedAt
    jurisdiction {
      id
      name
      assesses
      billDelivery
      bills
    }
    reportedBy {
      id
      name
      email
    }
  }
}
```

### search

`query`, returns [`SearchResults!`](/docs/types.md#searchresults), needs `PARCEL_READ`

Search the portfolio for parcels, units and documents at once. Fewer than two characters returns three empty lists.

Arguments:

- `first` (`Int`, default 8): How many per list: 8 when omitted, at most 20.
- `query` (`String!`, required): What to look for.

Example:

```graphql
query ($query: String!) {
  search(query: $query) {
    parcels {
      id
      parcelNumber
      status
      useCode
    }
    jurisdictions {
      id
      name
      assesses
      billDelivery
      bills
    }
  }
}
```

### team

`query`, returns [`[User!]!`](/docs/types.md#user), signed-in people only

The people of your own firm who can sign in, by name. For people signed in to the app; a request made with a key is refused.

Example:

```graphql
{
  team {
    id
    name
    email
    tenant {
      id
      name
      kind
    }
  }
}
```

### viewer

`query`, returns [`User!`](/docs/types.md#user), any key

Who this request acts as: the signed-in person, or the service user the API key stands for.

Example:

```graphql
{
  viewer {
    id
    name
    email
    tenant {
      id
      name
      kind
    }
  }
}
```