> ## Documentation Index > Fetch the complete documentation index at: https://docs.arrays.org/llms.txt > Use this file to discover all available pages before exploring further. # Get PIT Dividends > [OpenAPI JSON Spec](/docs/output/v1_stocks_dividends_get.json) **Feature Overview** Get Point-in-Time (PIT) dividend data for a specific symbol within a time range. **Main Use Cases** - **Dividend Analysis**: Track historical dividend payments and distributions - **Income Planning**: Analyze dividend frequency and yield trends - **Investment Research**: Study dividend history for income-focused portfolios - **Backtesting**: Historical dividend data for quantitative analysis - **Tax Planning**: Review dividend payment dates and amounts **Query Parameters & Logic** **Required Parameters:** - `symbol`: Stock symbol (e.g., AAPL, MSFT, KO) - `start_time`: Start timestamp (Unix seconds, UTC) - `end_time`: End timestamp (Unix seconds, UTC) - `time_type`: Date type to filter by (RECORD_DATE, PAYMENT_DATE, or DECLARATION_DATE) **Optional Parameters:** - `limit`: Maximum number of results (1-1000, default: 50) **Validation Rules:** - Symbol is required and must be a valid stock symbol - start_time must be before end_time - time_type must be one of: RECORD_DATE, PAYMENT_DATE, DECLARATION_DATE - Limit defaults to 50 if not provided, max 1000 **Response Data Structure** - `data` ([]PITDividendData): Array of PIT dividend data points **PITDividendData fields:** - `symbol` (string): Stock symbol - `date` (string): Ex-dividend date (YYYY-MM-DD) - `record_date` (string): Record date (YYYY-MM-DD) - `payment_date` (string): Payment date (YYYY-MM-DD) - `declaration_date` (string): Declaration date (YYYY-MM-DD) - `adj_dividend` (float64): Adjusted dividend amount - `dividend` (float64): Dividend amount - `yield` (float64): Dividend yield percentage - `frequency` (string): Dividend frequency (e.g., "Quarterly", "Monthly") **Dividend Date Explanation:** - **Declaration Date**: Date when board announces dividend (use time_type=DECLARATION_DATE) - **Ex-Dividend Date**: Date when stock trades without dividend - **Record Date**: Date to be on record to receive dividend (use time_type=RECORD_DATE) - **Payment Date**: Date when dividend is actually paid (use time_type=PAYMENT_DATE) **Usage Examples** 1. **Get AAPL dividends by payment date for 2024**: `?symbol=AAPL&start_time=1704067200&end_time=1735689600&time_type=PAYMENT_DATE` 2. **Get by record date with custom limit**: `?symbol=KO&start_time=1704067200&end_time=1735689600&time_type=RECORD_DATE&limit=100` 3. **Get by declaration date**: `?symbol=MSFT&start_time=1640995200&end_time=1735689600&time_type=DECLARATION_DATE&limit=1000` **Important Notes** - All required parameters must be provided - Results are ordered by the specified time_type date (typically descending) - PIT dividends provide point-in-time snapshots as they were known historically - Choose time_type based on your use case: RECORD_DATE for eligibility, PAYMENT_DATE for cash flow, DECLARATION_DATE for announcements ## OpenAPI ````yaml /api-reference/openapi.json get /v1/stocks/dividends openapi: 3.0.0 info: contact: {} description: >- Welcome to Arrays! Arrays is a unified financial data layer for both financial institutions and retail users, delivering comprehensive market data across crypto and equity markets. Our datasets cover fundamentals, ETFs, options, crypto, and more. Visit [arrays.org](https://arrays.org) to request an API key and start your free trial. You can explore our full API offerings in the documentation below. For any questions regarding APIs or pricing, please contact support@arrays.org. title: Arrays API version: '1.0' servers: - url: https://data-tools.prd.arrays.org/api security: [] paths: /v1/stocks/dividends: get: tags: - Stock summary: Get PIT Dividends description: >- [OpenAPI JSON Spec](/docs/output/v1_stocks_dividends_get.json) **Feature Overview** Get Point-in-Time (PIT) dividend data for a specific symbol within a time range. **Main Use Cases** - **Dividend Analysis**: Track historical dividend payments and distributions - **Income Planning**: Analyze dividend frequency and yield trends - **Investment Research**: Study dividend history for income-focused portfolios - **Backtesting**: Historical dividend data for quantitative analysis - **Tax Planning**: Review dividend payment dates and amounts **Query Parameters & Logic** **Required Parameters:** - `symbol`: Stock symbol (e.g., AAPL, MSFT, KO) - `start_time`: Start timestamp (Unix seconds, UTC) - `end_time`: End timestamp (Unix seconds, UTC) - `time_type`: Date type to filter by (RECORD_DATE, PAYMENT_DATE, or DECLARATION_DATE) **Optional Parameters:** - `limit`: Maximum number of results (1-1000, default: 50) **Validation Rules:** - Symbol is required and must be a valid stock symbol - start_time must be before end_time - time_type must be one of: RECORD_DATE, PAYMENT_DATE, DECLARATION_DATE - Limit defaults to 50 if not provided, max 1000 **Response Data Structure** - `data` ([]PITDividendData): Array of PIT dividend data points **PITDividendData fields:** - `symbol` (string): Stock symbol - `date` (string): Ex-dividend date (YYYY-MM-DD) - `record_date` (string): Record date (YYYY-MM-DD) - `payment_date` (string): Payment date (YYYY-MM-DD) - `declaration_date` (string): Declaration date (YYYY-MM-DD) - `adj_dividend` (float64): Adjusted dividend amount - `dividend` (float64): Dividend amount - `yield` (float64): Dividend yield percentage - `frequency` (string): Dividend frequency (e.g., "Quarterly", "Monthly") **Dividend Date Explanation:** - **Declaration Date**: Date when board announces dividend (use time_type=DECLARATION_DATE) - **Ex-Dividend Date**: Date when stock trades without dividend - **Record Date**: Date to be on record to receive dividend (use time_type=RECORD_DATE) - **Payment Date**: Date when dividend is actually paid (use time_type=PAYMENT_DATE) **Usage Examples** 1. **Get AAPL dividends by payment date for 2024**: `?symbol=AAPL&start_time=1704067200&end_time=1735689600&time_type=PAYMENT_DATE` 2. **Get by record date with custom limit**: `?symbol=KO&start_time=1704067200&end_time=1735689600&time_type=RECORD_DATE&limit=100` 3. **Get by declaration date**: `?symbol=MSFT&start_time=1640995200&end_time=1735689600&time_type=DECLARATION_DATE&limit=1000` **Important Notes** - All required parameters must be provided - Results are ordered by the specified time_type date (typically descending) - PIT dividends provide point-in-time snapshots as they were known historically - Choose time_type based on your use case: RECORD_DATE for eligibility, PAYMENT_DATE for cash flow, DECLARATION_DATE for announcements parameters: - description: Stock symbol (e.g., AAPL, MSFT, KO) in: query name: symbol required: true schema: type: string - description: Start timestamp (Unix seconds, UTC) in: query name: start_time required: true schema: type: integer format: int64 - description: End timestamp (Unix seconds, UTC) in: query name: end_time required: true schema: type: integer format: int64 - description: Date type to filter by in: query name: time_type required: true schema: type: string enum: - RECORD_DATE - PAYMENT_DATE - DECLARATION_DATE - description: 'Maximum number of results (1-1000, default: 50)' in: query name: limit schema: type: integer format: int32 default: 50 responses: '200': description: Successfully returns PIT dividends content: application/json: schema: allOf: - $ref: '#/components/schemas/model.APIResponse' - properties: data: items: $ref: '#/components/schemas/model.PITDividendData' type: array type: object '400': description: Parameter validation error content: application/json: schema: allOf: - $ref: '#/components/schemas/model.APIResponse' - properties: data: $ref: '#/components/schemas/model.APIError' type: object '404': description: Stock symbol not found content: application/json: schema: allOf: - $ref: '#/components/schemas/model.APIResponse' - properties: data: $ref: '#/components/schemas/model.APIError' type: object '500': description: Internal server error - gRPC service failure content: application/json: schema: allOf: - $ref: '#/components/schemas/model.APIResponse' - properties: data: $ref: '#/components/schemas/model.APIError' type: object security: - ApiKeyAuth: [] components: schemas: model.APIResponse: properties: data: {} error: $ref: '#/components/schemas/model.APIError' metadata: {} pagination: {} request_id: type: string success: type: boolean type: object model.PITDividendData: properties: adj_dividend: description: Adjusted dividend amount type: number date: description: Ex-dividend date in YYYY-MM-DD format type: string declaration_date: description: Declaration date in YYYY-MM-DD format type: string dividend: description: Dividend amount type: number frequency: description: Dividend frequency (Monthly, Quarterly, etc.) type: string payment_date: description: Payment date in YYYY-MM-DD format type: string record_date: description: Record date in YYYY-MM-DD format type: string symbol: description: Stock symbol type: string yield: description: Dividend yield percentage type: number type: object model.APIError: properties: code: example: RESOURCE_NOT_FOUND type: string details: items: $ref: '#/components/schemas/model.APIErrorDetail' type: array docs_url: type: string examples: items: type: string type: array hint: type: string message: example: The requested resource was not found. type: string suggestions: items: type: string type: array type: object model.APIErrorDetail: properties: field: type: string got: type: string reason: type: string type: object securitySchemes: ApiKeyAuth: description: 'API Key authentication. Example: "your-api-key-here"' in: header name: X-API-Key type: apiKey ````