---
title: "Signals First"
method: POST
path: "/functions/v1/api/v2/signals-first"
tags: ["Signals"]
---

# Signals First

`POST /functions/v1/api/v2/signals-first`

## Request

- Base URL: `https://api.signaliz.com`
- URL: `https://api.signaliz.com/functions/v1/api/v2/signals-first`
- Auth: HTTP bearer

Signals First asks any natural-language signal question and discovers up to 100 evidence-backed signals across distinct companies. Callers provide only query and limit; Signaliz owns the evidence window and source selection. Every returned signal includes its type, title, summary, company name, root domain, date, and source URL. Signals First is included on eligible plans: credits_used and credits_charged are zero when billing_status is included. Resume the returned signal_search_run_id to recover an interrupted search. A request is a ceiling, not a promise: fewer results are returned when public evidence cannot verify both a date and company identity.

## Headers

- `Idempotency-Key` string

## Request body

- union: Ask one natural-language signal question and choose how many distinct companies to return. Signaliz owns the evidence window and source selection.
  - object
    - `query` string, required: Any natural-language signal question. Recently funded companies and AI implementation signals are examples, not limits.
    - `limit` integer: Maximum distinct companies to return with evidence-backed signals. On a signal_search_run_id resume, an explicit limit changes the number of returned companies.
    - `signal_search_run_id` string: Resume a prior workspace-bound Signals First run. Use with a larger limit to return more companies from that run.
  - object
    - `query` string: Any natural-language signal question. Recently funded companies and AI implementation signals are examples, not limits.
    - `limit` integer: Maximum distinct companies to return with evidence-backed signals. On a signal_search_run_id resume, an explicit limit changes the number of returned companies.
    - `signal_search_run_id` string, required: Resume a prior workspace-bound Signals First run. Use with a larger limit to return more companies from that run.

## Response `200`

Signal discovery completed or dry-run planned.

- SignalsEverythingResult
  - `success` boolean, required
  - `status` 'planned' | 'queued' | 'processing' | 'partial' | 'completed' | 'completed_with_warnings' | 'failed', required
  - `capability` 'signals_everything', required
  - `signal_search_run_id` string: Present for queued, processing, and completed searches; omitted for a no-dispatch dry run.
  - `query` string
  - `requested_count` integer
  - `stage` string
  - `progress` integer
  - `message` string
  - `next_poll_after_seconds` integer
  - `signals` SignalDiscoveryItem[], required
    - `signal_type` string, required: Open-vocabulary, source-supported signal classification.
    - `signal_title` string, required: Source-backed signal headline when available.
    - `signal_summary` string, required: Source-backed signal summary when available.
    - `source` string, uri, required: Verified source URL supporting the signal.
    - `date` string, date, required: Published date of the supporting evidence.
    - `company_name` string, required: Resolved company name. Always present on returned signals.
    - `domain` string, required: Resolved company domain.
  - `signal_count` integer, required
  - `idempotency_replayed` boolean
  - `cache_hit` boolean: True when this response was served from a retained Signals First run.
  - `live_provider_called` boolean: True only when this request called a live search provider.
  - `result_returned_from` 'stored_signal_search_run'
  - `credits_used` 0
  - `credits_charged` 0
  - `billing_status` 'included'
  - `error` string
  - `error_code` string
  - `retry_eligible` boolean
  - `retry_after_seconds` integer

## Other responses

- `202`: Signal discovery is still running; retry with the returned signal_search_run_id.
- `403`: Signals First is available on Builder, Team, and Agency plans.
- `422`: The request could not be completed.
- `429`: Rate limited. Retry after the indicated delay.

---

[API](https://skmtc.dev/signaliz/apis/signaliz-api.md) · [All operations](https://skmtc.dev/signaliz/apis/signaliz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signaliz/apis/signaliz-api/revisions/53cb64feddad?raw)