/api/v1/sniper/targets

Create a new Sniper Target.

Why use this

Schedule a monitoring job for a specific ticker — the Sniper module fires WS push notifications + webhook callbacks the moment a matching SEC filing arrives for the ticker during the active window. Used for time-bounded high-conviction monitoring (e.g. 'watch TSLA for 10-K release tonight') rather than long-running watchlist subscriptions. Each target moves through a 3-state lifecycle: `CREATED` (target stored, not yet active) -> `ACTIVE` (within `start_time .. end_time` window, monitoring) -> `STOPPED` (window expired, manual stop, or filing-hit terminal). Pricing: `cost: 0` to create the target itself, but each TARGET COSTS A TIER PER ACTIVE PERIOD against the customer's plan — see the per-tier sniper allowance in the Account section.

Common use case

Setting up an automated buy trigger for TSLA immediately upon 10-K release — customer creates a sniper target with `ticker=TSLA`, `duration_minutes=120` to cover the expected after-market filing window. When the 10-K filing hits SEC EDGAR, the Sniper fires (a) a WS push to active connections, (b) an HTTP POST to the customer's configured webhook URL (see [Webhooks > POST {your_webhook_url}](/docs/webhooks/webhooks/post-webhook-url)). Also useful for activist-tracker workflows ('watch ULTA for 13D/G release in next 5 trading days').

Schedule a Sniper monitoring job for a specific ticker — the Sniper module fires WS push notifications + webhook callbacks the moment a matching SEC filing arrives during the active window. Designed for time-bounded high-conviction monitoring (earnings windows, expected 13D/G filings, M&A close dates) rather than long-running watchlist subscriptions. Each target moves through a 3-state lifecycle: CREATED (stored, future start) -> ACTIVE (monitoring) -> STOPPED (window expired / manual stop / filing-hit terminal). Pricing: target creation is cost: 0 but each ACTIVE TARGET consumes one slot from the customer's plan-allocated sniper budget — Free tier gets 0 sniper slots, Paid tier gets 5 concurrent active targets. Pair with Webhooks > POST {your_webhook_url} for receiving the event payload, or use the WS streaming endpoints (/ws/main-api, /ws/insider-api) for push notifications without operating a webhook receiver. Token consumption for sniper hits is logged in GET /api/v1/account/usage and GET /api/v1/account/transactions.

Parameters

Name	In	Required	Default	Allowed	Description	Example
ticker	body	required	—	—	Canonical hyphen-form ticker (e.g. `BRK-A` not `BRK.A`). Server applies the v3.14.2 ticker-normalization shim. Returns 400 when the ticker is unknown to the catalog (run [GET /api/v1/cusip/ticker/{ticker}](/docs/reference-data/cusip-api/get-cusip-ticker) to verify before creating the target).	AAPL
duration_minutes	body	optional	60	—	How long to monitor (1-1440). When `start_time` and `end_time` are both omitted, the target activates IMMEDIATELY and runs for `duration_minutes` from creation. When `start_time` is provided, runs from `start_time` for `duration_minutes`. Mutually exclusive with `end_time` (provide either `duration_minutes` OR `end_time`, not both).	—
start_time	body	optional	—	—	ISO 8601 UTC start time. Omit for immediate activation. Useful for scheduling monitoring of upcoming earnings windows (e.g. `start_time=2026-04-30T20:00:00Z` for an after-market AAPL 10-Q expected at 8pm UTC).	2026-01-01T00:00:00Z
end_time	body	optional	—	—	ISO 8601 UTC end time. Mutually exclusive with `duration_minutes`. Server returns 400 when both are provided. Maximum window is 24 hours from `start_time`.	2026-04-01T00:00:00Z
form_types	body	optional	—	—	Optional array of SEC form types to filter on. Omit to fire on ANY new filing for the ticker; provide to restrict (e.g. `["10-K", "10-Q"]` for earnings-only).	["10-K", "10-Q", "8-K"]
webhook_url	body	optional	—	—	Optional customer webhook URL to POST the event payload to when the sniper fires. Falls back to the customer's account-level default webhook URL if omitted (configured under `/account/settings/webhooks`).	https://customer.example.com/sniper-callback

Response schema

Field	Type	Nullable	Description
status	string	no	Booking created.
request_id	string	yes	Request correlation identifier, when available.
timestamp	string	no	Response generation timestamp in UTC.
data	object	no	The existing SniperTarget serializer output; a booking is not proof of filing delivery.
data.id	integer	no	Numeric booking identifier.
data.user_id	string	no	Owning account identifier.
data.ticker	string	no	Ticker stored for this booking.
data.cik	string	no	SEC registrant identifier.
data.target_accession	string	no	Predicted filing accession number.
data.target_url	string	no	Predicted filing address.
data.status	string	yes	Stored monitoring status, separate from processing_state.
data.hit_url	string	yes	Detected filing address, if any.
data.start_time	string	yes	Stored monitoring start; ISO timestamp, without an added timezone suffix.
data.end_time	string	yes	Stored monitoring end; ISO timestamp, without an added timezone suffix.
data.created_at	string	yes	Stored creation timestamp.
data.updated_at	string	yes	Stored last-update timestamp.
data.filing_uuid	string	yes	Linked filing identifier, if processed.
data.processing_state	string	yes	Filing-processing stage, if recorded.
data.parsed_at	string	yes	Stored parsing timestamp.
data.enriched_at	string	yes	Stored enrichment timestamp.
data.period_of_report	string	yes	Linked filing reporting date, if available.
data.last_baselined_at	string	yes	Stored prediction-refresh timestamp.
data.baseline_source	string	yes	Prediction source, if recorded.
data.holdings_count	integer	yes	Parsed holdings count, if recorded.
data.candidate_urls	array	yes	Predicted filing candidates; a candidate URL may be null for a rollover marker.
data.candidate_urls[].accession	string	no	Optional; omitted when not applicable.
data.candidate_urls[].url	string	yes	Optional; omitted when not applicable.

Sample response

"status": "success"
"request_id": null
"timestamp": "2026-09-19T12:00:00Z"
"data":
- "id": 1
- "user_id": "example-account"
- "ticker": "TEST"
- "cik": "0000000001"
- "target_accession": "0000000001-26-000001"
- "target_url": "https://www.sec.gov/Archives/edgar/data/1/0000000001-26-000001.txt"
- "status": "active"
- "hit_url": null
- "start_time": "2026-09-19T12:00:00"
- "end_time": "2026-09-19T13:00:00"
- "created_at": "2026-09-19T12:00:00"
- "updated_at": "2026-09-19T12:00:00"
- "filing_uuid": null
- "processing_state": null
- "holdings_count": null
- "parsed_at": null
- "enriched_at": null
- "candidate_urls": null
- "period_of_report": null
- "last_baselined_at": "2026-09-19T12:00:00"
- "baseline_source": "db_primary"
}

}

Errors

Status	Label	Description
200	OK	Request succeeded.
400	Bad Request	Invalid query, body, or path parameter.
401	Unauthorized	Missing or invalid Authorization header / api_Token.
402	Payment Required	Insufficient token balance for this call. Top up
429	Too Many Requests	Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500	Server Error	Unexpected server-side failure. Retry with backoff; report if persistent.

Code samples

Reveal credentials

curl -X POST "https://api.finradar.ai/api/v1/sniper/targets" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ticker": "AAPL",
  "start_time": "2026-01-01T00:00:00Z",
  "end_time": "2026-04-01T00:00:00Z",
  "form_types": "[\"10-K\", \"10-Q\", \"8-K\"]",
  "webhook_url": "https://customer.example.com/sniper-callback"
}'

Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).