/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
target_id	string	no	Unique target identifier (format: `tgt_<base62-12chars>`). Pass to [POST /api/v1/sniper/targets/{target_id}/stop](/docs/sniper/sniper-module/post-sniper-targets-target-id-stop) for early cancellation, or to [GET /api/v1/sniper/targets](/docs/sniper/sniper-module/get-sniper-targets) when paginating.
ticker	string	no	Echoed canonical hyphen-form ticker.
status	string	no	Lifecycle state — `CREATED` (target stored but `start_time` is in the future), `ACTIVE` (currently monitoring; this is the typical immediate-creation state), `STOPPED` (terminal — window expired, manual stop, or filing-hit fired).
start_time	string	no	ISO 8601 UTC start of the monitoring window. Either explicitly provided or set to creation time.
end_time	string	no	ISO 8601 UTC end of the monitoring window. Computed from `start_time + duration_minutes` when `duration_minutes` was provided.
form_types	array	yes	Echoed form-type filter array. Null when no filter was provided (fires on ANY new filing).
webhook_url	string	yes	Echoed webhook URL — either the explicit per-target URL or the account-level default. Null when no webhook is configured (the sniper still fires WS push but skips HTTP webhook).
created_at	string	no	ISO 8601 UTC creation timestamp (server-side).
filing_uuid	string	yes	Foreign key to `filings.uuid` once the hit has been parsed and ingested. Null until the 13F parse pipeline reaches the `parsed` or later `processing_state`.
processing_state	string	yes	Parse-pipeline stage, orthogonal to `status`. One of: `detected` (filing URL captured, parse queued), `parsing` (parser running), `parsed` (holdings extracted), `enriched` (OpenFIGI ticker enrichment complete), `no_holdings` (13F-NT or empty holdings table), `parse_failed` (parse error; sniper falls back to bare filing-URL notification). Null until the sniper has fired at least one hit.
holdings_count	integer	yes	Number of holdings rows extracted from `form_13f_holdings` when `processing_state` is `parsed` or later. Null when parse has not completed or the filing carries no holdings table (13F-NT).
parsed_at	string	yes	ISO 8601 UTC timestamp when the 13F parse pipeline completed (`processing_state` transitioned to `parsed`). Null until parse completes.
enriched_at	string	yes	ISO 8601 UTC timestamp when OpenFIGI ticker enrichment completed (`processing_state` transitioned to `enriched`). Null until enrichment completes or if enrichment is skipped.
candidate_urls	array	yes	Range-scan window of predicted filing URLs assembled at target creation time — array of `{ accession: string, url: string }` objects. Lets clients pre-render expected filing links before the sniper actually fires. Null when no range-scan was performed.

Sample response

"target_id": "tgt_abc123def456"
"ticker": "TSLA"
"status": "ACTIVE"
"start_time": "2026-05-02T20:00:00Z"
"end_time": "2026-05-02T22:00:00Z"
"form_types":
- "10-K"
- "10-Q"
- "8-K"
]
"webhook_url": "https://customer.example.com/sniper-callback"
"created_at": "2026-05-02T19:58:42Z"
"filing_uuid": null
"processing_state": null
"holdings_count": null
"parsed_at": null
"enriched_at": null
"candidate_urls": null

}

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 "Authorization: Bearer YOUR_JWT_TOKEN"

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