Get Started with the SEC API

This API provides programmatic access to SEC filing data, including insider transactions, periodic reports, ownership disclosures, and other submissions filed by reporting companies.

Use the links in this section for authentication, rate limits, and error handling — plus guides for each supported form type (Form 4, 8-K, 10-K, and others).

Authentication

Create an account or log in to create and manage API keys

All API requests must include an API key. In production, the supported and preferred approach is the
x-api-key HTTP header on every request.

Request header (preferred in production)

curl

curl -H "x-api-key: YOUR_API_KEY" https://api.finsider.io/api/v1/sec/submissions

For local development and quick experiments, you can also pass the same value as the apiKey query parameter when the header is missing or you need a quick URL-only test. Do not rely on query parameters in production: URLs are often logged, cached, or shared. The API evaluates the x-api-key header before considering apiKey in the query string.

Query parameter (development only)

Example URL

https://api.finsider.io/api/v1/sec/submissions?apiKey=YOUR_API_KEY

Security notice

Keep your API keys secure. Never share your API keys in client-side code or public repositories. Avoid apiKey in URLs outside local development—request logs and referrers can expose them.

Rate Limiting

Tier Limits

Tier	Requests/Minute	Requests/Hour	Requests/Day	Monthly Cost
Free	10	30	50	`$0`
Lite	500	5,000	50,000	`$29`
Pro	5,000	50,000	500,000	`$49`
Enterprise	20,000	200,000	2,000,000	`$490`

Rate Limit Headers

All API responses include the following headers to help you track your rate limit status:

Header	Description	Example
`X-RateLimit-Limit`	Maximum number of requests allowed in the current period	`100`
`X-RateLimit-Remaining`	Number of requests remaining in the current period	`99`
`X-RateLimit-Reset`	Unix timestamp when the rate limit resets	`1609459200`
`X-RateLimit-Used`	Number of requests made in the current period	`1`

Rate Limit Exceeded Response

When you exceed your rate limit, the API will respond with a 429 Too Many Requests status code and the following response:

JSON

{  "error": {    "code": "rate_limit_exceeded",    "message": "API rate limit exceeded",    "details": {      "reset_at": "2023-01-01T00:00:00Z",      "limit": 100,      "remaining": 0,      "retry_after": 45    }  }}

Best Practices for Rate Limits

Implement proper error handling for 429 responses
Use the X-RateLimit-Remaining header to track your usage
Implement exponential backoff when retrying after rate limit errors
Cache API responses when possible to reduce the number of requests
Distribute requests evenly instead of sending them in bursts
Consider upgrading your plan if you consistently hit rate limits

Error Handling

Error Response Format

All API errors return a standardized JSON response with the following structure:

JSON

{  "error": {    "code": "string",       // Machine-readable error code    "message": "string",    // Human-readable error description    "details": { },         // Additional context-specific error details    "request_id": "string"  // Unique identifier for the request (for support)  }}

HTTP Status Codes

Status	Code	Description	Example
`400`	`bad_request`	The request was malformed or contains invalid parameters	Missing required field
`401`	`unauthorized`	Authentication is required or credentials are invalid	Invalid API key
`403`	`forbidden`	Client does not have permission to access the resource	Subscription expired
`404`	`not_found`	The requested resource could not be found	Entity doesn't exist
`422`	`validation_failed`	The request was valid but the server couldn't process it	Invalid date format
`429`	`rate_limit_exceeded`	The client has sent too many requests	Too many requests
`500`	`server_error`	Something went wrong on the server	Internal exception
`503`	`service_unavailable`	The service is temporarily unavailable	Maintenance mode

Error Examples

400 Bad Request

JSON

{  "error": {    "code": "bad_request",    "message": "Missing required field: ticker",    "details": {      "field": "ticker",      "reason": "required"    },    "request_id": "req_7h4k2j3h4k2j3h4k2j3h"  }}

401 Unauthorized

JSON

{  "error": {    "code": "unauthorized",    "message": "Invalid API key provided",    "details": {      "reason": "invalid_key"    },    "request_id": "req_9s8d7f6g5h4j3k2l1"  }}

429 Rate Limit Exceeded

JSON

{  "error": {    "code": "rate_limit_exceeded",    "message": "Monthly API request limit exceeded for your subscription tier",    "details": {        "monthly_limit": 10,        "subscription_plan": "FREE",        "reason": "rate_limit_exceeded",        "current_usage": 10,        "reset_date": "Next month"    },    "request_id": "req_1a2b3c4d5e6f7g8h9i"  }}

Best Practices

Practice	Category	Benefit
Use HTTPS Only	Security	Encrypt data in transit for all API requests
Secure API Keys	Security	Never expose keys in client-side code; use environment variables server-side
Implement Authorization	Security	Apply access controls so users only see authorized data
Validate All Inputs	Security	Sanitize and validate inputs to prevent injection and unexpected behavior
Implement Caching	Performance	Cache responses locally to reduce network requests and improve responsiveness
Use Compression	Performance	Enable gzip/brotli for requests and responses to reduce data transfer
Optimize Payload Size	Performance	Request only needed data using params like `fields` when available
Batch Requests	Performance	Combine related requests into single API calls when possible
Implement Retry Logic	Reliability	Use exponential backoff for retries to handle temporary failures
Monitor Rate Limits	Reliability	Track usage and implement client-side rate limiting to avoid disruptions
Handle Errors Properly	Reliability	Implement comprehensive error handling for clear user feedback and stability
Version Your Integrations	Development	Specify API versions in requests to ensure stability as the API evolves
Test in Sandbox	Development	Test integrations thoroughly in sandbox before production
Maintain Backward Compatibility	Development	Design for resilience to API changes and new response fields