> ## Documentation Index > Fetch the complete documentation index at: https://docs.thebuoy.app/llms.txt > Use this file to discover all available pages before exploring further. # List satellite altimeter passes > List recorded satellite altimeter passes over virtual buoys. Filter to a single satellite with `mission` — a slug returned by `GET /buoys/satellites` (e.g. `cfosat`). An unknown slug returns `404`. ## OpenAPI ````yaml /api-reference/openapi.json get /buoys/satellite_passes openapi: 3.0.3 info: title: The Buoy API version: 2.0.0 description: >- **The Buoy API** — programmatic access to ocean wave buoys on The Surf Kit platform. All operations are **read-only** (`GET`). Data includes live and historical readings, geographic filters, chart time series, and **`GET /conditions`** (combined forecast, buoy reading, and tide for a point). ## Authentication Pass your API key in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` `GET /buoys/search` and `GET /buoys/nearest` are public (no key required). ## Rate limiting Responses include `X-RateLimit-*` headers. Exceeding your hourly quota returns `429 Too Many Requests`. contact: name: API Support email: thomas@thebuoy.app license: name: Proprietary servers: - url: https://api.thebuoy.app/v2 description: Production server (V2) - url: http://localhost:3000/api/v2 description: Development server (V2) security: - ApiKeyAuth: [] tags: - name: Buoys description: Real-time ocean buoy data - name: Satellite Passes description: >- Satellite altimeter passes over virtual buoys, and the missions behind them - name: Conditions description: All-in-one conditions endpoint paths: /buoys/satellite_passes: get: tags: - Satellite Passes summary: List satellite altimeter passes description: | List recorded satellite altimeter passes over virtual buoys. Filter to a single satellite with `mission` — a slug returned by `GET /buoys/satellites` (e.g. `cfosat`). An unknown slug returns `404`. operationId: listSatellitePasses parameters: - name: mission in: query description: >- Filter passes to a single satellite mission, by slug (see `GET /buoys/satellites`). schema: type: string example: cfosat - name: active_only in: query description: >- When true (default), return only passes that have fresh, displayable buoy readings. schema: type: boolean default: true - name: since in: query description: Only return passes at or after this ISO 8601 timestamp. schema: type: string format: date-time example: '2026-05-01T00:00:00Z' - name: limit in: query description: 'Maximum number of passes to return (default: 20, max: 100).' schema: type: integer default: 20 minimum: 1 maximum: 100 responses: '200': description: Successful response headers: X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: type: object properties: status: type: string example: success data: type: object properties: satellite_passes: type: array items: $ref: '#/components/schemas/SatellitePass' count: type: integer '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' description: Unknown mission slug '429': $ref: '#/components/responses/RateLimitExceeded' security: - ApiKeyAuth: [] components: headers: XRateLimitLimit: schema: type: integer description: Maximum requests allowed per hour example: 1000 description: Maximum requests allowed per hour XRateLimitRemaining: schema: type: integer description: Requests remaining in current hour example: 987 description: Requests remaining in current hour XRateLimitReset: schema: type: integer description: Unix timestamp when rate limit resets example: 1735326000 description: Unix timestamp when rate limit resets schemas: SatellitePass: type: object properties: id: type: integer name: type: string example: Bay of Biscay pass · CFOSAT · 14 May 10:00 UTC external_id: type: string satellite_pass_id: type: string description: Alias of external_id. platform: type: string nullable: true description: Raw platform label stored on the pass. example: CFOSAT mission: allOf: - $ref: '#/components/schemas/SatelliteMissionRef' nullable: true description: Resolved satellite mission, or null when unknown. started_at: type: string format: date-time nullable: true ended_at: type: string format: date-time nullable: true buoy_count: type: integer observation_count: type: integer bounds: type: object nullable: true properties: south: type: number nullable: true west: type: number nullable: true north: type: number nullable: true east: type: number nullable: true SatelliteMissionRef: type: object description: Compact reference to a satellite mission. properties: slug: type: string example: cfosat name: type: string example: CFOSAT ErrorResponse: type: object description: Standardized error response format for V2 API properties: error: type: string description: >- Error code (e.g., "unauthorized", "bad_request", "resource_not_found") example: unauthorized message: type: string description: Human-readable error message example: Invalid API key details: type: object description: Additional error details (optional, varies by error type) responses: Unauthorized: description: Invalid or missing API key (401 Unauthorized) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: unauthorized message: Invalid API key timestamp: '2025-12-27T14:30:00Z' request_id: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: Resource not found (404 Not Found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: resource_not_found message: Couldn't find Spot with 'id'=999 timestamp: '2025-12-27T14:30:00Z' request_id: 550e8400-e29b-41d4-a716-446655440000 RateLimitExceeded: description: Rate limit exceeded (429 Too Many Requests) headers: X-RateLimit-Limit: schema: type: integer description: Maximum requests allowed per hour example: 1000 X-RateLimit-Remaining: schema: type: integer description: Requests remaining in current hour example: 0 X-RateLimit-Reset: schema: type: integer description: Unix timestamp when rate limit resets (top of next hour) example: 1735326000 Retry-After: schema: type: integer description: Seconds to wait before retrying example: 3600 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: rate_limit_exceeded message: You have exceeded 1000 requests per hour timestamp: '2025-12-27T14:30:00Z' request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API Key description: > API key authentication. Pass your API key as a Bearer token in the Authorization header. Format: `Authorization: Bearer YOUR_API_KEY` Alternative: Pass as query parameter `?api_key=YOUR_API_KEY` **Security:** API keys are stored as BCrypt hashes (never plain text). Only the hash is stored in the database. ````