Get company competitors

Returns the competitive landscape for a company, a ranked list of competitors, the dimensions the market splits on, and a short summary of the competitive landscape.

This endpoint uses 1 credit per request.

Behaviour

• companyId (the Specter company ID) is required in the path.
• Cache-first: a company that’s already been analysed returns instantly; one that’s never been analysed (or a request with refresh: true) computes the full landscape on demand and is slower.
• Results older than 30 days are recomputed automatically, so the landscape is never more than 30 days stale. last_updated reports when it was last computed.
• At most 30 competitors are returned; limit (1–30) only narrows that set — it can’t raise the ceiling above 30.
• The request body is optional — omit it to use the defaults (limit 30, refresh false).
• Returns 404 if the company doesn’t exist.

POST /companies/{companyId}/competitors

Get company competitors

cURL

curl --request POST \
  --url https://app.tryspecter.com/api/v1/companies/{companyId}/competitors \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "limit": 10,
  "refresh": false
}
'

import requests

url = "https://app.tryspecter.com/api/v1/companies/{companyId}/competitors"

payload = {
    "limit": 10,
    "refresh": False
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({limit: 10, refresh: false})
};

fetch('https://app.tryspecter.com/api/v1/companies/{companyId}/competitors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.tryspecter.com/api/v1/companies/{companyId}/competitors",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'limit' => 10,
    'refresh' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.tryspecter.com/api/v1/companies/{companyId}/competitors"

	payload := strings.NewReader("{\n  \"limit\": 10,\n  \"refresh\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.tryspecter.com/api/v1/companies/{companyId}/competitors")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"limit\": 10,\n  \"refresh\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.tryspecter.com/api/v1/companies/{companyId}/competitors")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"limit\": 10,\n  \"refresh\": false\n}"

response = http.request(request)
puts response.read_body

200

{
  "competitors": [
    {
      "company_id": "5e3a8f19040ca7b0c6f031f8",
      "name": "Adyen",
      "domain": "adyen.com",
      "competitiveness_score": 0.95,
      "dimensions": [
        "Omnichannel Payments"
      ],
      "focus": "Unified global payment and fraud platform."
    }
  ],
  "dimensions": [
    {
      "code": "omnichannel_payments",
      "label": "Omnichannel Payments",
      "description": "Unified in-store and online payment acceptance."
    }
  ],
  "summary_headline": "A crowded payments market led by full-stack platforms.",
  "summary_body": "<string>",
  "last_updated": "2026-06-01T00:00:00Z"
}

{
  "errorCode": "API_KEY_MISSING",
  "message": "No API Key was presented on the header X-API-KEY"
}

{
  "errorCode": "OUT_OF_CREDITS",
  "message": "<string>"
}

{
  "errorCode": "NOT_PERMITTED",
  "message": "You do not have permission to access this resource."
}

{
  "errorCode": "<string>",
  "message": "<string>"
}

{
  "errorCode": "<string>",
  "message": "<string>"
}

Authorizations

X-API-Key · string · header · required

Path Parameters

companyId · string · required

The Specter company ID.

Body

application/json

limit · integer · default: 30

Maximum number of competitors to return. 30 is also the hard ceiling — the endpoint never returns more than 30.

Required range: 1 <= x <= 30

refresh · boolean · default: false

Recompute the competitive landscape from scratch instead of serving the cached result. Use when you want the freshest analysis; expect a slower response.

Response

200

application/json

The company's competitive landscape, ranked competitors, the dimensions the market splits on, and a summary of the competitive landscape.

competitors · object[]

Competitors ranked by how directly they compete (closest first).

Show child attributes

dimensions · object[]

The dimensions the market splits on for this company.

Show child attributes

summary_headline · string | null

A one-line headline summarising the competitive set.

Example:

"A crowded payments market led by full-stack platforms."

summary_body · string | null

A short summary of the competitive landscape.

last_updated · string<date-time> | null

ISO 8601 timestamp of when this landscape was last computed. Results older than 30 days are recomputed automatically, so this is never more than 30 days in the past.

Example:

"2026-06-01T00:00:00Z"