> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Search an agent's file history > Searches the session outputs this agent's sessions saved, including outputs its subagents and teammates saved, which are what its sessions read with search_agent_files when the agent has fileHistoryEnabled. Structured and metadata conditions are exact and apply before paging; text searches the contents of text formats, and coverage reports the candidates it could not search in full. Every page reads the snapshot asOf names; pass nextCursor back with an otherwise unchanged request for the next page. Outputs of deleted sessions, of session analysts, and of sessions under an access policy are not included. ## OpenAPI ````yaml /managed-agents/openapi.yaml post /managed-agents/v1/agents/{agentId}/files/search openapi: 3.1.0 info: title: Managed Agents API version: 0.14.0 description: >- The Recursion Managed Agents REST API. Authenticate with a Recursion API key as a bearer token. An organization-scoped key acts in its own organization and needs nothing else; a tenant-scoped key must also send `x-organization-id` with an organization id or `default`. Field names follow each operation's published schema. servers: - url: https://api.recursion.labelbox.com security: - bearerAuth: [] paths: /managed-agents/v1/agents/{agentId}/files/search: post: tags: - Agents summary: Search an agent's file history description: >- Searches the session outputs this agent's sessions saved, including outputs its subagents and teammates saved, which are what its sessions read with search_agent_files when the agent has fileHistoryEnabled. Structured and metadata conditions are exact and apply before paging; text searches the contents of text formats, and coverage reports the candidates it could not search in full. Every page reads the snapshot asOf names; pass nextCursor back with an otherwise unchanged request for the next page. Outputs of deleted sessions, of session analysts, and of sessions under an access policy are not included. operationId: managedAgentsSearchAgentFiles parameters: - description: >- Agent id (UUID) as returned by managedAgentsCreateAgent or managedAgentsListAgents. in: path name: agentId required: true schema: description: >- Agent id (UUID) as returned by managedAgentsCreateAgent or managedAgentsListAgents. format: uuid type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' requestBody: content: application/json: schema: $ref: '#/components/schemas/AgentFileSearchRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentFileSearchResult' description: >- One page of an agent file search: the session outputs this agent's earlier sessions saved that match, with a cursor for the next page and the coverage of text search. headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' discriminator: propertyName: code mapping: invalid_json: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' invalid_request: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' x-recursion-error-codes: - invalid_json - invalid_request headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' x-recursion-error-codes: - unauthorized headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' x-recursion-error-codes: - forbidden headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '404': description: Not Found. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' x-recursion-error-codes: - not_found headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '413': description: Payload Too Large. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' x-recursion-error-codes: - payload_too_large headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '415': description: Unsupported Media Type. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' x-recursion-error-codes: - unsupported_media_type headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '422': description: Unprocessable Entity. content: application/json: schema: $ref: >- #/components/schemas/ManagedAgentsApiErrorContentIndexIncomplete x-recursion-error-codes: - content_index_incomplete headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Too Many Requests. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' x-recursion-error-codes: - rate_limit_exceeded '500': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' x-recursion-error-codes: - internal_error headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '502': description: A dependent service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyFailure' x-recursion-error-codes: - bad_gateway headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '503': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Service Unavailable. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: managed_agents_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable x-recursion-error-codes: - managed_agents_unavailable - service_unavailable '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: A dependent service timed out. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyTimeout' x-recursion-error-codes: - gateway_timeout components: parameters: RecursionTenantId: name: x-tenant-id in: header required: false description: >- Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is `default`. schema: type: string minLength: 1 RecursionOrganizationId: name: x-organization-id in: header required: false description: >- Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or `default`. schema: type: string minLength: 1 schemas: AgentFileSearchRequest: properties: cursor: description: >- nextCursor from the previous page. The rest of the request must be unchanged. type: string filter: $ref: '#/components/schemas/AgentFileFilter' description: Structured conditions. Omit to browse. limit: default: 20 description: Page size, default 20. maximum: 100 minimum: 1 type: - 'null' - integer sort: default: created_at_desc description: >- created_at_desc (default) lists newest first; relevance ranks by text match and needs text. enum: - created_at_desc - relevance type: string strictContent: default: false description: >- Fail with content_index_incomplete instead of returning results when some candidate files could not be text-searched. type: boolean text: description: >- Words to find in the text of the files. All words must appear; a quoted "phrase" must appear as written; OR between words matches either; -word excludes. Only text formats are searched, and coverage says what was not. type: string x-recursion-omission: strategy: absent type: object additionalProperties: false AgentFileSearchResult: description: >- One page of an agent file search: the session outputs this agent's earlier sessions saved that match, with a cursor for the next page and the coverage of text search. properties: asOf: description: >- The snapshot every page of this search reads: files saved after it are not included. format: date-time type: string coverage: $ref: '#/components/schemas/AgentFileCoverage' description: How completely the search covered the eligible files. items: description: Matching files, in the requested order. items: $ref: '#/components/schemas/AgentFile' type: array nextCursor: description: >- Opaque cursor for the next page, passed back unchanged with the same request; null on the last page. type: - 'null' - string total: description: >- Exact number of files matching every condition in this search's snapshot. format: int64 minimum: 0 type: integer maximum: 9007199254740991 required: - items - nextCursor - total - asOf - coverage type: object additionalProperties: false ManagedAgentsApiErrorInvalidJson: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_json message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInvalidRequest: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_request message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnauthorized: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unauthorized message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorForbidden: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - forbidden message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorNotFound: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - not_found message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPayloadTooLarge: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - payload_too_large message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnsupportedMediaType: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unsupported_media_type message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorContentIndexIncomplete: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - content_index_incomplete message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimitExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limit_exceeded message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInternalError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - internal_error message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyFailure: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorManagedAgentsUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - managed_agents_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorServiceUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - service_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyTimeout: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - gateway_timeout message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. AgentFileFilter: properties: createdAt: $ref: '#/components/schemas/AgentFileTimeRange' description: Matches outputs saved within this half-open time range. filenamePrefix: description: >- Matches outputs whose file name starts with this string, case-sensitive. type: string mediaTypes: description: Matches outputs of any of these media types, e.g. text/markdown. items: type: string maxItems: 20 minItems: 1 type: array uniqueItems: true metadata: description: Metadata conditions, all of which must hold. items: $ref: '#/components/schemas/AgentFileMetadataPredicate' maxItems: 16 minItems: 1 type: array uniqueItems: true pathPrefix: description: >- Matches outputs whose path under the outputs directory starts with this string, case-sensitive, e.g. reports/. type: string rootSessionIds: description: Matches outputs saved by any of these session trees. items: type: string maxItems: 50 minItems: 1 type: array uniqueItems: true type: object additionalProperties: false AgentFileCoverage: properties: content: description: >- For a text search, complete when every file that passed the structured conditions was text-searched in full; partial when some were not; not_requested without text. enum: - complete - partial - not_requested type: string metadata: description: >- Structured and metadata conditions are exact over every eligible file: always complete. enum: - complete type: string missing: description: Candidates whose text is not extracted yet. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 partial: description: Candidates whose text is indexed only up to the extraction cap. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 unsupported: description: Candidates whose format is not text-searched. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - metadata - content type: object additionalProperties: false AgentFile: properties: byteSize: description: Size in bytes. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 contentState: description: >- How much of the file's text content search covers: indexed in full, partial up to the extraction cap, unsupported format, or missing (not yet extracted). enum: - indexed - partial - unsupported - missing type: string createdAt: description: When the file was saved. format: date-time type: string fileId: description: The file's id, for read_agent_file and the file routes. type: string filename: description: The file's name. type: string mediaType: description: The file's media type. type: string metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Metadata the agent attached when it saved the file, without the reserved path key. type: object ownerAgentId: description: The agent whose history holds the file. type: string path: description: >- Where the output sat under the outputs directory of the session that saved it. type: string producerAgentVersionId: description: The agent version that session ran, when recorded. type: string producerSessionId: description: The session in that tree that wrote it, when recorded. type: string rootSessionId: description: The session tree that saved the file. type: string sha256: description: SHA-256 of the file's contents. type: string snippet: description: >- For a text search, a short excerpt around the first searched word, when found in the indexed text. type: string required: - fileId - path - filename - mediaType - byteSize - sha256 - ownerAgentId - rootSessionId - createdAt - contentState type: object additionalProperties: false ManagedAgentsApiErrorDetails: type: object properties: field: description: >- Request field or header responsible for the error, when one can be identified. type: string issues: description: >- Boundary-validation failures as path-prefixed human-readable messages. type: array items: type: string requestId: description: Request correlation identifier for support and log lookup. type: string retryable: description: >- Server advice about failure transience. `true` means transient, `false` means non-transient, and absence gives no advice. Automatic replay is allowed only when this field is not `false` and the operation-specific retry and idempotency contract permits replay. type: boolean additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. AgentFileTimeRange: properties: gte: description: Inclusive lower bound (RFC 3339). format: date-time type: - 'null' - string lt: description: Exclusive upper bound (RFC 3339). format: date-time type: - 'null' - string type: object additionalProperties: false AgentFileMetadataPredicate: properties: key: description: >- Top-level metadata key, in the metadata key alphabet (letters, digits, '_', '.', '-'). The reserved path key is filtered with pathPrefix instead. type: string op: description: >- eq matches one value of the same JSON type (null matches a stored null, not a missing key); in matches any of an array of values of one type; exists matches any stored value, null included; gt, gte, lt, and lte compare numbers with numbers and strings with strings. enum: - eq - in - exists - gt - gte - lt - lte type: string value: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- The value to compare. A string, number, boolean, or null for eq; an array of strings, numbers, or booleans for in; a number or string for the range operators; omitted for exists. Values are never coerced between types. required: - key - op type: object additionalProperties: false PlatformSafeJsonValue: description: >- A JSON value whose integer members stay within the exact ECMAScript safe-integer range at every nesting level. oneOf: - type: 'null' - type: boolean - type: string - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: number not: type: integer - type: array items: $ref: '#/components/schemas/PlatformSafeJsonValue' - additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object headers: RecursionOrganizationId: description: Organization id resolved for this request. schema: type: string minLength: 1 RecursionTenantId: description: Tenant id resolved for this request. schema: type: string minLength: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````