/api/v1/sniper/targets

List all active and past targets.

Why use this

List all sniper targets owned by the authenticated user — active (`status=ACTIVE`), pending (`status=CREATED`), and historical (`status=STOPPED`). The natural backend for a sniper-management dashboard. Filter by status to surface only currently-active monitoring jobs, or list all for an audit trail. Each target row includes lifecycle metadata (status / start / end times), the configured `form_types` filter, the webhook URL, and — for STOPPED targets — the resolution_reason (`window_expired` / `manual_stop` / `filing_hit`) and any associated `last_event` payload summary.

Common use case

Displaying a dashboard of ongoing monitoring tasks — show the user their currently-active snipers, snipers scheduled to start soon, and recently-stopped snipers with their resolution outcomes. Also useful for SLA audits ('did the sniper for our TSLA earnings target fire correctly?') and for plan-budget visibility ('how many of my 5 paid-tier sniper slots are currently active?').

List all sniper targets owned by the authenticated user — active, pending, and historical. The natural backend for a sniper-management dashboard. Filter by status=ACTIVE to surface currently-monitoring targets, or by ticker for per-ticker history. The meta.slots_available field surfaces the user's remaining plan-allocated sniper budget (Free tier = 0, Paid tier = 5 concurrent slots) — useful for rendering a 'X of 5 slots used' indicator in the UI before a new-target form. STOPPED targets carry a resolution_reason (window_expired / manual_stop / filing_hit) and — for filing-hit resolutions — a last_event payload with the accession number that fired the sniper. Pair with POST /api/v1/sniper/targets to create new targets and POST /api/v1/sniper/targets/{target_id}/stop to cancel active ones. Token consumption per sniper-hit is logged in GET /api/v1/account/usage.

Parameters

Name	In	Required	Default	Allowed	Description	Example
status	query	optional	—	—	Filter by lifecycle state — `CREATED` (pending future start) / `ACTIVE` (currently monitoring) / `STOPPED` (terminal). Omit for all states.	ACTIVE
ticker	query	optional	—	—	Filter by ticker (canonical hyphen form). Useful for 'show me all snipers I've ever created on AAPL' history queries.	TSLA
limit	query	optional	50	—	Max targets returned (1-200).	—
offset	query	optional	0	—	Pagination offset for chunked retrieval.	—

Response schema

Field	Type	Nullable	Description
targets	array	no	Array of sniper target rows owned by the authenticated user. Order: by `created_at DESC` (newest first). Empty array on users who have never created a sniper.
targets[].target_id	string	no	Unique target identifier (format: `tgt_<base62-12chars>`).
targets[].ticker	string	no	Canonical hyphen-form ticker.
targets[].status	string	no	Lifecycle state — `CREATED` / `ACTIVE` / `STOPPED`.
targets[].start_time	string	no	ISO 8601 UTC start of monitoring window.
targets[].end_time	string	no	ISO 8601 UTC end of monitoring window.
targets[].form_types	array	yes	Form-type filter array (null = fires on any filing).
targets[].webhook_url	string	yes	Webhook URL configured for this target. Null when no webhook is configured.
targets[].resolution_reason	string	yes	Terminal-state resolution — `window_expired` / `manual_stop` / `filing_hit`. Null while target is `CREATED` or `ACTIVE`.
targets[].last_event	object	yes	Most-recent matching SEC filing event for this target — `{ accession_number: string, form_type: string, filed_at: string }` for `filing_hit` resolutions, null otherwise.
targets[].created_at	string	no	ISO 8601 UTC creation timestamp.
targets[].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`.
targets[].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.
targets[].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).
targets[].parsed_at	string	yes	ISO 8601 UTC timestamp when the 13F parse pipeline completed (`processing_state` transitioned to `parsed`). Null until parse completes.
targets[].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.
targets[].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.
meta	object	no	Pagination + summary block: `{ total: integer, limit: integer, offset: integer, active_count: integer, slots_available: integer }`. `slots_available` shows the user's remaining plan-allocated sniper budget (5 - active_count for Paid tier, 0 for Free tier).

Sample response

"targets":
]
"meta":
- "total": 2
- "limit": 50
- "offset": 0
- "active_count": 1
- "slots_available": 4
}

}

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 "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).