API

Pull API とキー

API キーを作成し、GET /api/public/v1/events でイベントを取得し、カーソルでページを進め、pageToken で実行 Webhook のページを読み、signal.v1 を Webhook のイベントに対応付けます。

Pull API は、リクエストに応じて組織のイベントを返します。実行 Webhook のページの読み取り、履歴の取得、Webhook を受け取れない場合のポーリング、Webhook では送信されない LinkedIn エンゲージメントの取得に使います。

Webhook とは形が違います

pageToken なしの Pull API が返すのは signal.v1 オブジェクトです。Webhook の pageToken を付けると、イベントの形（version: 1）を返します。両者はキーが異なります。変換には対応表を使ってください。

API キーを作成する

開発者を開く

サイドバーで開発者を選びます。API キーセクションは一番上にあります。

キーを作成する

キーを作成をクリックします。チームがどこで使うキーかわかるよう、名前を入力し、もう一度キーを作成をクリックします。

今すぐコピーする

パネルに「表示は一度だけです。今すぐ保管してください。」と表示されます。キーをコピーをクリックし、シークレットマネージャーに保管してから、完了をクリックします。

開発者ページの API キー — キーは、作成日と無効化ボタンとともに一覧表示されます（画面は英語版）。

キーを削除するには、キーの横の無効化をクリックして確定します。そのキーを使っているものは、すぐに動かなくなります。元に戻せません。

キーは組織に属します。パスワードと同じように扱い、ブラウザや公開リポジトリには絶対に置かないでください。

リクエスト

bash

1curl "$SIGNALS_HOST/api/public/v1/events?limit=1" \
2  -H "x-api-key: $SIGNALS_API_KEY"

SIGNALS_HOST は、サインインするアプリのアドレスです。開発者ページの試してみるボックスに、正確なコマンドが表示されます。

キーは x-api-key ヘッダーで送ります。1 日のリクエスト数に上限はありません。リクエストは IP アドレスごとに 1 分あたり 30 件に制限されます。超えると Retry-After: 60 付きの 429 が返ります。

クエリパラメーター

pageTokenoptional

string

実行 Webhook の firstPageToken または nextPageToken。指定すると他のパラメーターはすべて無視され、レスポンスは実行のページになります。

cursoroptional

string

不透明な値。前のページの nextCursor を渡します。

limitoptional

integer

1 から 100。デフォルトは 30。範囲外の数値は範囲内に丸められます。整数でない値は 400 です。

sinceoptional

string

ISO 8601 の日付またはタイムスタンプ（例: 2026-10-14、2026-10-14T09:00:00Z）。この時刻以降に保存されたイベントのみ。それ以外の形式は 400 です。

projectIdoptional

string

特定のプロジェクトのイベントのみ。存在しない（または削除された）プロジェクトは 404 です。

trackerIdoptional

string

特定のトラッカーのイベントのみ。

sourceoptional

string

トラッカーのソース 1 つ: reviews、news、linkedin、linkedin_mentions、reddit_mentions、linkedin_engagement、x、instagram、ads、website、job_postings、competitor_discovery。それ以外の値は 400 です。

source は reddit_mentions を受け付けます

アプリ内のリファレンスの説明には、載っている値がもっと少なくなっています。API は、reddit_mentions や linkedin_engagement を含め、上記のすべてのソースを受け付けます。

削除されたプロジェクトのイベントは返されません。

レスポンス

json

1{
2  "items": [ /* signal.v1 objects, oldest first */ ],
3  "nextCursor": "eyJ…",
4  "hasMore": true
5}

レスポンス

items

signal.v1[]

イベント。Signals が保存した時刻の古い順です。

nextCursor

string|null

次のページを取得するには、これを cursor として渡します。最後のページでは null です。

hasMore

boolean

次のページがあるときは true です。

ステータス	意味
`200`	OK。
`400`	クエリパラメーターが無効です。ボディは `{ "error": "..." }` で、パラメーター名が示されます。
`401`	キーがない、無効、または無効化されています。
`403`	キーが Signals の組織に属していません。
`404`	`projectId` が組織の有効なプロジェクトではない、または Signals がオフになっています。
`429`	同じ IP から 1 分間に 30 件を超えるリクエストがありました。60 秒後に再試行してください。

実行 Webhook のページ

実行 Webhook には、イベント名ごとに firstPageToken が入ります。これを pageToken として渡します。

bash

1curl "$SIGNALS_HOST/api/public/v1/events?pageToken=$TOKEN" \
2  -H "x-api-key: $SIGNALS_API_KEY"

レスポンスは { run, eventName, total, page, totalPages, items, nextPageToken } です。items には、signal.v1 ではなくイベントの形のイベントが最大 100 件入ります。nextPageToken が null になるまでたどります。

ステータス	意味
`400`	トークンが変更された、途中で切れた、または Signals のものではありません。
`404`	実行がキーの組織にない、または Webhook が削除されました。
`410`	トークンが 30 日を過ぎています。`GET /api/public/v1/events?trackerId=…&since=…` で実行を読み取り、`runId` が実行の `id` と一致する要素だけを残してください。

項目、例、そのまま使えるループは実行のイベントを読むにあります。

新しいイベントをポーリングする

ページは古い順に返されるため、先へ進みながら、イベントを取りこぼすことはありません。nextCursor は最後のページで null になるため、ブックマークとして再利用できません。見た中で最新のイベントの detectedAt を保存し、次回のポーリングで since として使い、id で重複を排除してください。

ページを取得する

GET /api/public/v1/events?limit=100&since=…。since には前回保存した detectedAt から 10 分ほど前の時刻を指定します。

各イベントを処理する

items を順に処理します。処理済みの id は飛ばします。

カーソルをたどる

hasMore が true の間は、cursor に nextCursor を指定して再度リクエストします。

位置を保存する

見た中で最新の detectedAt を保存し、数分後の次回のポーリングで使います。

since なしの最初の実行では、履歴全体を読み取ります。後から始めたい場合は、since を指定してください。

signal.v1 のフィールド

signal.v1

schema

'signal.v1'

オブジェクトのバージョン。

type

string

イベント名。例: reviews.new、ads.new、website.changed、jobs.new、engagement.new。

id

string

イベント ID。Webhook のページの eventId と同じ値です。

orgId

string

あなたの組織。

trackerId

string

イベントを見つけたトラッカー。

projectIdoptional

string

トラッカーのプロジェクト。存在しないのは、トラッカーがすでに存在せず、かつプロジェクトの導入前に保存されたイベントの場合だけです。

runId

string

イベントを見つけたトラッカーの実行。

source

string

トラッカーのソース。例: reviews、ads、job_postings、linkedin_engagement。

subject

object

競合: { key: string, display: string }。display は競合の名前です。

change

'added'|'updated'|'removed'

項目に何が起きたか。

changeSeq

number

Signals の変更ログ内の位置。項目ごとではなく、組織のすべてのイベントを通して増えます。

itemKey

string

ソース内での項目の識別子。

observedAt

string|null

項目が公開または観測された時刻（ISO 8601）。removed では null です。

detectedAt

string

Signals が変更を検出した時刻（ISO 8601）。

item

object

共通の項目フィールド: title、text、url、author、metrics、media。意味はイベントの形と同じです。

detail

object|null

レビューの rating など、ソース固有のフィールド。removed では null です。

relevance

object

関連性の判定結果: { status: 'unjudged' } または { status: 'relevant', … }。イベントの形をご覧ください。

signal.v1Signals の実行で得た実際のイベント

json

1{
2  "schema": "signal.v1",
3  "type": "ads.new",
4  "id": "617692b7-2c85-499c-bc3b-6810f3673190",
5  "orgId": "org_3KikADUjsyXrUJ4RJhWpwcp98Yf",
6  "trackerId": "3c8918c2-7011-4518-9185-31344c83861f",
7  "runId": "b0b5b63b-fc3d-4eef-84ab-879e2335c06d",
8  "source": "ads",
9  "subject": {
10    "key": "google:AR10072600183532683265@-|meta:https://www.facebook.com/hubspot|linkedin:hubspot",
11    "display": "HubSpot"
12  },
13  "change": "added",
14  "changeSeq": 254,
15  "itemKey": "ads|google|CR00389017023612452865",
16  "observedAt": "2025-07-30T14:52:54.000Z",
17  "detectedAt": "2026-10-27T20:28:40.624Z",
18  "item": {
19    "title": null,
20    "text": null,
21    "url": null,
22    "author": {
23      "name": "Hubspot, Inc."
24    },
25    "metrics": null,
26    "media": [
27      {
28        "type": "image",
29        "url": "https://tpc.googlesyndication.com/archive/simgad/13161062113949559550"
30      }
31    ]
32  },
33  "detail": {
34    "source": "ads",
35    "kind": "ad",
36    "adSource": "google",
37    "externalId": "CR00389017023612452865",
38    "format": "text",
39    "isActive": true,
40    "startedAt": "2025-07-30T14:52:54.000Z",
41    "endedAt": null,
42    "previewUrl": "https://adstransparency.google.com/advertiser/AR10072600183532683265/creative/CR00389017023612452865?region=anywhere",
43    "cta": null,
44    "landingUrl": null,
45    "paidBy": null,
46    "postedBy": null,
47    "logoUrl": null,
48    "daysShown": 455
49  },
50  "relevance": {
51    "status": "unjudged"
52  }
53}

signal.v1 · linkedin_engagement（Pull API のみ）Signals の実行で得た実際のイベント

json

1{
2  "schema": "signal.v1",
3  "type": "engagement.new",
4  "id": "1742a36b-08e8-477d-8f35-10b3d6207930",
5  "orgId": "org_3KikADUjsyXrUJ4RJhWpwcp98Yf",
6  "trackerId": "271e9142-1ab6-41ad-b905-3d58e065e71d",
7  "runId": "57a0369d-23f8-4aa5-86db-6c64b3cea6e4",
8  "source": "linkedin_engagement",
9  "subject": {
10    "key": "engagement:hubspot|posts:5",
11    "display": "HubSpot"
12  },
13  "change": "added",
14  "changeSeq": 27,
15  "itemKey": "linkedin_engagement|7520919497038557184|acoaac8dmlgbxyqanprimg25nxbncr5bqy0hpe8",
16  "observedAt": "2026-10-27T20:28:38.954Z",
17  "detectedAt": "2026-10-27T20:28:38.954Z",
18  "item": {
19    "title": "Diksha Sabharwal",
20    "text": "B2B Marketing Strategy | Lifecycle Operations | MS in Marketing Analytics",
21    "url": "https://www.linkedin.com/in/ACoAAC8DMLgBxyqaNpRiMg25NxBNcR5bQY0HPE8",
22    "author": {
23      "name": "Diksha Sabharwal",
24      "handle": "acoaac8dmlgbxyqanprimg25nxbncr5bqy0hpe8",
25      "url": "https://www.linkedin.com/in/ACoAAC8DMLgBxyqaNpRiMg25NxBNcR5bQY0HPE8"
26    },
27    "metrics": {},
28    "media": []
29  },
30  "detail": {
31    "source": "linkedin_engagement",
32    "kind": "person",
33    "personHandle": "acoaac8dmlgbxyqanprimg25nxbncr5bqy0hpe8",
34    "name": "Diksha Sabharwal",
35    "headline": "B2B Marketing Strategy | Lifecycle Operations | MS in Marketing Analytics",
36    "profileUrl": "https://www.linkedin.com/in/ACoAAC8DMLgBxyqaNpRiMg25NxBNcR5bQY0HPE8",
37    "how": "reacted",
38    "reaction": "ENTERTAINMENT",
39    "commentText": null,
40    "postUrn": "7520919497038557184",
41    "postUrl": "https://www.linkedin.com/feed/update/urn:li:activity:7520919497038557184/",
42    "postTitle": "Which of these is “frighteningly” on brand? 👻"
43  },
44  "relevance": {
45    "status": "unjudged"
46  }
47}

signal.v1 から Webhook イベントへ

`signal.v1`（Pull API）	Webhook イベント（ページの要素）	備考
`schema: "signal.v1"`	`version: 1`	バージョンの付け方が異なります。
`type`	`signalType`	名前は同じです。
`id`	`eventId`	同じ値です。
`change`	`action`	`added` → `new`、`updated` → `updated`、`removed` → `removed`。
`changeSeq`	`sequence`	同じ数値です。
`observedAt`	`occurredAt`	削除された項目では、どちらも `null` です。
`subject` `{ key, display }`	`competitor` `{ name, domain, subjectKey }`	`display` → `name`、`key` → `subjectKey`。Webhook では `domain` が加わります。
`item` + `detail`	`<family>Response` と `metadata`	Webhook は、項目のフィールドとソースのフィールドを 1 つのオブジェクトにまとめます。それを、種類のキー（例: `reviewResponse`）と `metadata` の 2 か所に入れて送ります。
`source`	`source`、さらに `eventType` と `subEventType`	Webhook では、ソースを種類とプラットフォームにも分けます。
`orgId`、`trackerId`、`projectId`、`runId`、`itemKey`、`detectedAt`、`relevance`	同じ名前	Webhook では、`itemKey` の `

LinkedIn エンゲージメントには、Webhook イベントがありません。ここで source=linkedin_engagement を指定して取得してください。

リファレンス

機械可読な OpenAPI 仕様とインタラクティブなビューアーは、Signals ホストの /api/public/docs にあります。先にサインインしてください。

Webhook の仕組み

ポーリングの代わりに、イベントを push で受け取ります。

実行のイベントを読む

実行 Webhook のイベントをページごとに読み取ります。

よくある質問

イベントと配信についてのよくある質問です。