---
title: "Search"
method: POST
path: "/api/v1/funds/subject-app-limits/search"
tags: ["Subject App Limits"]
---

# Search

`POST /api/v1/funds/subject-app-limits/search`

## Request

- Base URL: `https://example.conductor.one`
- URL: `https://example.conductor.one/api/v1/funds/subject-app-limits/search`
- Auth: HTTP bearer and OAuth 2
  - Client credentials
  - Token URL: `/auth/v1/token`

Search the tenant's subject-app limit rows. Reads the Postgres mirror:
 the runtime row is keyed on (tenant, subject), so a tenant-wide listing
 has no runtime query at all. Filters narrow by subject, by app, and by
 state; empty filters return every live row in the tenant.

 POST rather than GET: the filters are repeated fields, which the gateway
 cannot carry as query parameters. Pagination is keyset-based over
 (pksk), the storage primary key, so a concurrent write to a filtered
 field cannot duplicate or omit a row across pages the way an offset page
 can.

## Request body

- C1ApiFundsV1SubjectAppLimitServiceSearchRequest: The SubjectAppLimitServiceSearchRequest message.
  - `appIds` string[], nullable: Restrict to these apps; empty returns every app.
  - `pageSize` integer: The pageSize field.
  - `pageToken` string: The pageToken field.
  - `states` C1ApiFundsV1SubjectAppLimitStateFilter: SubjectAppLimitStateFilter is the structured state filter. The three states are mutually exclusive by construction: suspended is suspension present; explicit-limit is suspension absent AND limit present; inheriting is neither. Combining them is a union. Unset (all false) does not filter by state at all.
    - `explicitLimit` boolean: No suspension and a limit arm is present, whatever it states. True for the seeded support case: "show me everyone with an explicit per-app number".
    - `inheriting` boolean: No suspension and no limit: the row exists but states no opinion, so resolution falls through it. No compliant write persists such a row — the clearing verbs delete it — so a match is a legacy or corrupt row, which is exactly what an admin auditing "which rows are doing nothing" needs the filter to surface.
    - `suspended` boolean: A suspension is present: the app is paused for this subject. A row that also carries a limit is still suspended — the suspension is what its subject experiences.
  - `userIds` string[], nullable: Restrict to these subjects; empty returns every row in the tenant.

## Response `200`

Successful response

- C1ApiFundsV1SubjectAppLimitServiceSearchResponse: The SubjectAppLimitServiceSearchResponse message.
  - `list` C1ApiFundsV1SubjectAppLimit[], nullable: The list field.
    - `appId` string: The C1 App this limit applies to.
    - `controls` C1ApiFundsV1SpendControls: SpendControls retains coexisting base, extension and suspension state.
      - `extension` C1ApiFundsV1SpendExtension: SpendExtension replaces the base total temporarily; it is not additive credit.
        - `expiresAt` string, date-time, nullable
        - `limit` C1ApiFundsV1SpendLimit: SpendLimit distinguishes an amount, unlimited tracking and blocked supply. This message contains a oneof named kind. Only a single field of the following list may be set at a time: - unlimited - amount - blocked
          - `amount` C1ApiFundsV1SpendLimitAmount: The SpendLimitAmount message.
            - `money` C1ApiFundsV1Money: Money is a non-negative monetary value used by spending controls.
              - …
          - `blocked` C1ApiFundsV1SpendLimitBlocked: The SpendLimitBlocked message.
          - `unlimited` C1ApiFundsV1SpendLimitUnlimited: The SpendLimitUnlimited message.
        - `reason` string: The reason field.
      - `limit` C1ApiFundsV1SpendLimit: SpendLimit distinguishes an amount, unlimited tracking and blocked supply. This message contains a oneof named kind. Only a single field of the following list may be set at a time: - unlimited - amount - blocked
        - `amount` C1ApiFundsV1SpendLimitAmount: The SpendLimitAmount message.
          - `money` C1ApiFundsV1Money: Money is a non-negative monetary value used by spending controls.
            - `currencyCode` string: ISO 4217 currency code.
            - `nanos` integer: Fractional nano-units, from zero through 999999999.
            - `units` string, int64: Whole currency units. The bound keeps nano-unit conversion within int64.
        - `blocked` C1ApiFundsV1SpendLimitBlocked: The SpendLimitBlocked message.
        - `unlimited` C1ApiFundsV1SpendLimitUnlimited: The SpendLimitUnlimited message.
      - `period` 'PERIOD_KIND_UNSPECIFIED' | 'PERIOD_KIND_DAILY' | 'PERIOD_KIND_WEEKLY' | 'PERIOD_KIND_MONTHLY' | 'PERIOD_KIND_QUARTERLY' | 'PERIOD_KIND_YEARLY': The period field.
      - `suspension` C1ApiFundsV1SpendSuspension: SpendSuspension preserves the underlying controls while refusing new spend.
        - `reason` string: The reason field.
        - `suspendedAt` string, date-time, nullable
    - `createdAt` string, date-time, nullable
    - `deletedAt` string, date-time, nullable
    - `tenantId` string: The tenantId field.
    - `updatedAt` string, date-time, nullable
    - `userId` string: Canonical c1.models.user.v2.User id.
  - `nextPageToken` string: The nextPageToken field.

## Changes

- **2026-10-20** `fe943bedf41b`: 1 breaking, 1 info
  - added `#/components/schemas/c1.api.funds.v1.SpendControls` to the `list/items/controls` response property `oneOf` list for the response status `200`
  - removed `#/components/schemas/c1.models.funds.v1.SpendControls` from the `list/items/controls` response property `oneOf` list for the response status `200`
- **2026-10-06** `918a4e749f56`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/conductorone/apis/c1-api/changes/api/v1/funds/subject-app-limits/search/post.md)

---

[API](https://skmtc.dev/conductorone/apis/c1-api.md) - [All operations](https://skmtc.dev/conductorone/apis/c1-api/llms.txt) - [OpenAPI document](https://skmtc.dev/conductorone/apis/c1-api/revisions/fe943bedf41b?raw)