API REFERENCE

Create measurement job

On this page

POST/api/research/measurement-jobs

Create a current capture or enqueue historical the configured research data connection backfill. Provide exactly one of catalog_id, album_ids or isrcs in scope; platforms supports spotify only. source=current uses the snapshot pipeline and returns an ID that can be passed to Create catalog. source=historical requires a card on file, resolves scope recordings and returns id:null with enqueued/skipped counts; it attempts to start the existing budget-gated backfill workflow, with daily maintenance as a backstop. Enqueue success is not capture completion or evidence of complete historical coverage. Songs with any historical research measurement are skipped, including potentially partial history. Historical enqueue itself makes no credit deduction; current capture estimates and provider/account gates remain separate.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/research/measurement-jobs' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": {
    "isrcs": [
      "USQY51771120"
    ]
  },
  "source": "historical",
  "platforms": [
    "spotify"
  ]
}'

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

Request bodyapplication/json

cURL for this request

curl --request POST \
  --url 'https://api.recoupable.dev/api/research/measurement-jobs' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": {
    "isrcs": [
      "USQY51771120"
    ]
  },
  "source": "historical",
  "platforms": [
    "spotify"
  ]
}'

Request body required

application/json

scopeobjectrequired

Provide exactly one of catalog_id, album_ids, or isrcs.

Properties

catalog_idstring

format: uuid

album_idsarray<string>

Item properties

string

isrcsarray<string>

Item properties

string

sourcestring · enumrequired

current captures present counts through the snapshot pipeline; historical enqueues the configured research data connection backfill. Historical requires a saved payment method and does not promise complete history.

Values: "current", "historical"

platformsarray<string · enum>

Default: ["spotify"]

Example: ["spotify"]

Item properties

string · enum · "spotify"

Responses

202Job accepted.

application/json

oneOf · object 1

statusstring · enumrequired

Values: "success"

sourcestring · enumrequired

Values: "current"

idstringrequired

Snapshot ID for current captures.

format: uuid

statestringrequired

State returned by the snapshot pipeline; reused captures need not be queued.

album_countintegerrequired

estimated_cost_usdnumberrequired

reusedboolean

Present when an existing capture is handed back.

oneOf · object 2

statusstring · enumrequired

Values: "success"

sourcestring · enumrequired

Values: "historical"

idnullrequired

No pollable snapshot ID is created for historical backfill.

enqueuedintegerrequired

Recordings submitted to the backfill queue; this does not mean history is captured.

skippedintegerrequired

Recordings with any existing historical research measurement; skipping does not prove complete history.

400Invalid scope/source/platform, or no recordings resolvable from the selected historical scope.

application/json

statusstring · enumrequired

Values: "error"

Example: "error"

errorstringrequired

Human-readable error message describing what went wrong.

Example: "Missing required parameter: artist"

401Authentication failed — invalid or missing API key.

application/json

statusstring · enumrequired

Values: "error"

Example: "error"

errorstringrequired

Human-readable error message describing what went wrong.

Example: "Missing required parameter: artist"

402Historical backfill requires an existing saved payment method. If unavailable, returns a neutral entitlement error without creating a card-setup or checkout session. Preserve the job request; do not retry automatically.

application/json

statusstring · enumrequired

Values: "error"

errorstring · enumrequired

Values: "payment_method_required"

messagestringrequired

Neutral explanation that the feature is unavailable with current account entitlements.

429Per-organization monthly cap reached.

application/json

statusstring · enumrequired

Values: "error"

Example: "error"

errorstringrequired

Human-readable error message describing what went wrong.

Example: "Missing required parameter: artist"

500Internal, enqueue or provider configuration error.

application/json

statusstring · enumrequired

Values: "error"

Example: "error"

errorstringrequired

Human-readable error message describing what went wrong.

Example: "Missing required parameter: artist"

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download research.json

View operation source

json

{
  "operationId": "postResearchMeasurementJobs",
  "summary": "Create a measurement job",
  "description": "Create a current capture or enqueue historical the configured research data connection backfill. Provide exactly one of catalog_id, album_ids or isrcs in scope; platforms supports spotify only. source=current uses the snapshot pipeline and returns an ID that can be passed to [Create catalog](/api-reference/songs/catalogs-create). source=historical requires a card on file, resolves scope recordings and returns id:null with enqueued/skipped counts; it attempts to start the existing budget-gated backfill workflow, with daily maintenance as a backstop. Enqueue success is not capture completion or evidence of complete historical coverage. Songs with any historical research measurement are skipped, including potentially partial history. Historical enqueue itself makes no credit deduction; current capture estimates and provider/account gates remain separate.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ResearchMeasurementJobRequest"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Job accepted.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchMeasurementJobResponse"
          }
        }
      }
    },
    "400": {
      "description": "Invalid scope/source/platform, or no recordings resolvable from the selected historical scope.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Authentication failed — invalid or missing API key.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "402": {
      "description": "Historical backfill requires an existing saved payment method. If unavailable, returns a neutral entitlement error without creating a card-setup or checkout session. Preserve the job request; do not retry automatically.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "status",
              "error",
              "message"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "error"
                ]
              },
              "error": {
                "type": "string",
                "enum": [
                  "payment_method_required"
                ]
              },
              "message": {
                "type": "string",
                "description": "Neutral explanation that the feature is unavailable with current account entitlements."
              }
            }
          }
        }
      }
    },
    "429": {
      "description": "Per-organization monthly cap reached.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal, enqueue or provider configuration error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    }
  }
}

Historical backfill requires an existing saved payment method. A missing method returns HTTP 402 with error: "payment_method_required" and a neutral message. The request does not create a checkout session or start card setup. Preserve the request and stop; do not poll the denied operation or initiate a purchase.

Get started with Recoup.

Try Our Platform

Build Your Platform

Create measurement job

Authentication

Request

Try it

Request body required

Responses

Full specification