> ## Documentation Index > Fetch the complete documentation index at: https://docs.story.foundation/llms.txt > Use this file to discover all available pages before exploring further. # List Disputes > Retrieve a paginated, filtered list of disputes from the SOS database. This endpoint supports various filtering options including: - Filter by dispute ID, target IP ID, initiator address, or status - Filter by block number ranges (blockNumber, blockNumberLte, blockNumberGte) - Sort by block number, dispute timestamp, or ID - Pagination with configurable limit and offset Key v4 Enhancements: - Flattened request structure: Query parameters are directly in the request body, not nested in an "options" object - Offset-based pagination: Unlike v3, this endpoint supports both limit and offset parameters for flexible pagination - Block number range filtering: Added blockNumberGte for greater-than-or-equal filtering (complements existing blockNumberLte) - Pagination metadata in response: Returns total count and hasMore flag The response format is aligned with v3 for compatibility, using big integers for numeric fields and hex strings for data fields. ## OpenAPI ````yaml https://api.storyapis.com/api/v4/openapi.json post /disputes openapi: 3.1.0 info: description: Story Protocol API V4 title: Story Protocol API V4 version: v4 servers: - url: https://api.storyapis.com/api/v4 - url: https://staging-api.storyprotocol.net/api/v4 - description: Local development server url: http://localhost:8080/api/v4 security: [] paths: /disputes: post: tags: - Protocol V4 - Disputes summary: List Disputes description: >- Retrieve a paginated, filtered list of disputes from the SOS database. This endpoint supports various filtering options including: - Filter by dispute ID, target IP ID, initiator address, or status - Filter by block number ranges (blockNumber, blockNumberLte, blockNumberGte) - Sort by block number, dispute timestamp, or ID - Pagination with configurable limit and offset Key v4 Enhancements: - Flattened request structure: Query parameters are directly in the request body, not nested in an "options" object - Offset-based pagination: Unlike v3, this endpoint supports both limit and offset parameters for flexible pagination - Block number range filtering: Added blockNumberGte for greater-than-or-equal filtering (complements existing blockNumberLte) - Pagination metadata in response: Returns total count and hasMore flag The response format is aligned with v3 for compatibility, using big integers for numeric fields and hex strings for data fields. operationId: listDisputesV4 requestBody: content: application/json: schema: $ref: '#/components/schemas/DisputesRequestBodyHuma' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListDisputesResponseHumaBody' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/ErrorModel' description: Error security: - ApiKeyAuth: [] components: schemas: DisputesRequestBodyHuma: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://api.storyapis.com/api/v4/DisputesRequestBodyHuma.json format: uri readOnly: true type: string orderBy: description: Field to order results by (must be blockNumber or empty) type: string orderDirection: description: Order direction for results (asc or desc) type: string pagination: $ref: '#/components/schemas/DisputePaginationHuma' description: Pagination configuration where: $ref: '#/components/schemas/DisputeWhereHuma' description: Filter options for disputes type: object ListDisputesResponseHumaBody: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://api.storyapis.com/api/v4/ListDisputesResponseHumaBody.json format: uri readOnly: true type: string data: description: List of disputes items: $ref: '#/components/schemas/Dispute' type: - array - 'null' pagination: $ref: '#/components/schemas/DisputePaginationMetadataHuma' description: Pagination metadata (v4 enhancement, not in v3) required: - data type: object ErrorModel: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://api.storyapis.com/api/v4/ErrorModel.json format: uri readOnly: true type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object DisputePaginationHuma: additionalProperties: false properties: limit: default: 100 description: 'Number of items to return (max: 200)' examples: - 100 format: int64 maximum: 200 minimum: 1 type: integer offset: default: 0 description: Number of items to skip for pagination (v4 enhancement) examples: - 0 format: int64 minimum: 0 type: integer type: object DisputeWhereHuma: additionalProperties: false properties: blockNumber: description: Filter by exact block number examples: - '1500000' pattern: ^[0-9]+$ type: string blockNumberGte: description: Filter by block number >= this value (v4 enhancement) examples: - '1000000' pattern: ^[0-9]+$ type: string blockNumberLte: description: Filter by block number <= this value examples: - '2000000' pattern: ^[0-9]+$ type: string id: description: Dispute ID to filter by examples: - '123' pattern: ^[0-9]+$ type: string initiator: description: Initiator wallet address to filter by examples: - '0xabcdef1234567890abcdef1234567890abcdef12' pattern: ^0x[a-fA-F0-9]{40}$ type: string targetIpId: description: Target IP ID to filter by examples: - '0x1234567890abcdef1234567890abcdef12345678' pattern: ^0x[a-fA-F0-9]{40}$ type: string type: object Dispute: additionalProperties: false properties: arbitrationPolicy: type: string blockNumber: type: - string - 'null' blockTimestamp: type: string counterEvidenceHash: type: string currentTag: type: string data: type: string deletedAt: type: string disputeTimestamp: type: - string - 'null' evidenceHash: type: string id: type: - string - 'null' initiator: type: string liveness: type: - string - 'null' logIndex: type: string status: type: string targetIpId: type: string targetTag: type: string transactionHash: type: string umaLink: type: string required: - id - targetIpId - targetTag - currentTag - arbitrationPolicy - evidenceHash - initiator - data - blockNumber - disputeTimestamp - transactionHash - status - counterEvidenceHash - liveness type: object DisputePaginationMetadataHuma: additionalProperties: false properties: hasMore: description: Whether there are more disputes type: boolean limit: description: Current limit format: int64 type: integer offset: description: Current offset format: int64 type: integer total: description: Total count of disputes format: int64 type: integer required: - offset - limit - hasMore type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object securitySchemes: ApiKeyAuth: in: header name: X-Api-Key type: apiKey ````