> ## Documentation Index > Fetch the complete documentation index at: https://broker-docs.newyorkcityservers.com/llms.txt > Use this file to discover all available pages before exploring further. # List Requests > List and filter the service requests in your broker account. Returns a paginated list of service requests that belong to the authenticated broker. The full endpoint is `GET /api/v1/requests`. The request does not have a body. ## Filtering And Order The API applies all specified filters before it applies `offset` and `limit`. It sorts matching requests by `submitted_date` in descending order. The date boundaries are inclusive. You can use a date, such as `2026-05-01`, or a timestamp, such as `2026-05-31T23:59:59Z`. The `pagination.page` value is `floor(offset / limit) + 1`. Use an `offset` that is a multiple of `limit` when you need predictable page numbers. ## Errors Error responses use `success: false` and an `error` object. | HTTP status | Error code | Cause | | ----------- | -------------------------- | ------------------------------------------------------------------------------------------- | | `400` | `invalid_parameter` | `status`, `type`, or `source` is not an accepted value. | | `400` | `invalid_parameter` | `submitted_after` or `submitted_before` cannot be parsed as a date. | | `401` | `authentication_failed` | The Bearer token is missing, invalid, inactive, or expired. | | `403` | `insufficient_permissions` | The key does not have `requests:read` or `admin:full`. | | `403` | `insufficient_permissions` | The request IP address is not allowed for the key. | | `429` | `rate_limit_exceeded` | The key reached its rate limit. The `Retry-After` header contains the wait time in seconds. | | `500` | `server_error` | The API could not get the requests or could not complete the request. | ## OpenAPI ````yaml api/openapi.yaml GET /v1/requests openapi: 3.1.0 info: title: Broker API version: 1.0.0 description: API for broker-scoped service, request, and report operations. servers: - url: https://brokers.newyorkcityservers.com/api description: Broker Panel API security: - bearerAuth: [] tags: - name: Authentication - name: Services - name: Requests - name: Reports paths: /v1/requests: get: tags: - Requests summary: List Requests description: >- Lists broker-owned service requests with offset pagination and filters. Requires `requests:read` or `admin:full`. operationId: listRequests parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 20 - name: offset in: query schema: type: integer minimum: 0 default: 0 - name: status in: query schema: type: string enum: - pending - approved - denied - name: type in: query schema: type: string enum: - new-service - upgrade - downgrade - cancellation - cancellation-warning - revert - welcome-email - name: source in: query schema: type: string enum: - manual - form - api - name: search in: query description: >- Case-insensitive client name/email search or exact public request ID. schema: type: string - name: submitted_after in: query description: >- Inclusive date or timestamp parseable by JavaScript Date.parse; ISO 8601 is recommended. schema: type: string - name: submitted_before in: query description: >- Inclusive date or timestamp parseable by JavaScript Date.parse; ISO 8601 is recommended. schema: type: string - name: include_custom_data in: query description: Only the literal value true includes sanitized public custom data. schema: type: boolean default: false responses: '200': description: Paginated request list. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: - data - pagination properties: data: type: array items: $ref: '#/components/schemas/ServiceRequest' pagination: $ref: '#/components/schemas/Pagination' example: success: true data: - request_id: REQ-000123 type: new-service request_status: pending client_name: Example Trading Ltd client_email: admin@example.com client_phone: +1-212-555-0100 current_plan: null requested_plan: Standard VPS notes: New client setup submitted_date: '2026-05-12T10:30:00.000Z' processed_date: null processed_by_user: null processed_by_email: null denial_reason: null source: api form_id: null pagination: page: 1 perPage: 20 total: 1 totalPages: 1 '400': description: Code `invalid_parameter` for an invalid enum or date filter. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: invalid_parameter message: >- Invalid type. Must be one of: new-service, upgrade, downgrade, cancellation, cancellation-warning, revert, welcome-email details: parameter: type valid_values: - new-service - upgrade - downgrade - cancellation - cancellation-warning - revert - welcome-email '401': $ref: '#/components/responses/AuthenticationError' '403': $ref: '#/components/responses/PermissionError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/ServerError' components: schemas: SuccessEnvelope: type: object required: - success properties: success: type: boolean const: true message: type: string pagination: $ref: '#/components/schemas/Pagination' ServiceRequest: type: object required: - request_id - type - request_status - client_name - client_email - client_phone - current_plan - requested_plan - notes - submitted_date - processed_date - processed_by_user - processed_by_email - denial_reason - source - form_id properties: request_id: type: string pattern: ^REQ-[0-9]{6,}$ type: type: string enum: - new-service - upgrade - downgrade - cancellation - cancellation-warning - revert - welcome-email request_status: type: string enum: - pending - processing - approved - denied client_name: type: string client_email: type: string format: email client_phone: type: - string - 'null' current_plan: type: - string - 'null' requested_plan: type: - string - 'null' notes: type: - string - 'null' submitted_date: type: string format: date-time processed_date: type: - string - 'null' format: date-time processed_by_user: oneOf: - $ref: '#/components/schemas/Processor' - type: 'null' processed_by_email: type: - string - 'null' format: email denial_reason: type: - string - 'null' source: type: string enum: - manual - form - api form_id: type: - string - 'null' format: uuid custom_data: type: - object - 'null' additionalProperties: true Pagination: type: object required: - page - perPage - total - totalPages properties: page: type: integer minimum: 1 perPage: type: integer minimum: 1 maximum: 100 total: type: integer minimum: 0 totalPages: type: integer minimum: 0 ErrorResponse: type: object required: - success - error properties: success: type: boolean const: false error: $ref: '#/components/schemas/Error' Processor: type: object properties: name: type: - string - 'null' email: type: - string - 'null' format: email Error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true responses: AuthenticationError: description: >- Code `authentication_failed` for a missing, malformed, invalid, inactive, or expired API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: authentication_failed message: Invalid API key PermissionError: description: >- Code `insufficient_permissions` when the request IP is not whitelisted or a required scope is missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: insufficient_permissions message: IP address not whitelisted RateLimitError: description: Code `rate_limit_exceeded` when the API key exceeds its rate limit. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: rate_limit_exceeded message: Rate limit exceeded ServerError: description: >- Code `server_error` when authentication or internal processing cannot complete. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: server_error message: Internal server error securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Send the API key in the Authorization bearer header. Production keys begin with `sk_live_`. ````