Analysis

Request AI analysis

POST

/interviews/{id}/analysis

Starts AI analysis of a completed interview. Then poll GET /interviews/{id}/analysis (analysis usually takes a few minutes).

202: analysis was queued (also when a previous analysis failed, which retries it).
200: analysis is already pending, processing or completed. Nothing new is queued, and the current state is returned, including result if it's completed.
409: the interview isn't completed.

The Videcoot user who created the API key gets an email when the analysis finishes or fails.

Path parameters

idstringrequiredpattern ^[0-9a-fA-F]{24}$
A 24-character hex ID.

Example: "66f3a1c2e4b0a1d2c3e4f530"

Responses

202

Analysis was queued.

Body AnalysisResponse

dataAnalysisrequired
- statusstringrequired
  Values: "not_requested", "pending", "processing", "completed", "failed"
- requestedAtstring (date-time) | nullrequired
- completedAtstring (date-time) | nullrequired
- resultone ofrequired
  Present once status is completed; otherwise null.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "data": {
    "status": "pending",
    "requestedAt": "2026-09-26T03:00:00.000Z",
    "completedAt": null,
    "result": null
  },
  "timestamp": 1790398800000
}

200

Analysis was already requested. The current state is returned.

Body AnalysisResponse

dataAnalysisrequired
- statusstringrequired
  Values: "not_requested", "pending", "processing", "completed", "failed"
- requestedAtstring (date-time) | nullrequired
- completedAtstring (date-time) | nullrequired
- resultone ofrequired
  Present once status is completed; otherwise null.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "data": {
    "status": "processing",
    "requestedAt": "2026-09-26T03:00:00.000Z",
    "completedAt": null,
    "result": null
  },
  "timestamp": 1790398830000
}

400

The request is invalid. message is the first validation error.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "success": false,
  "message": "limit must be between 1 and 100",
  "timestamp": 1790330400000
}

401

The API key is missing, malformed, invalid or revoked.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

{
  "success": false,
  "message": "API key is required. Send it as 'Authorization: Bearer <key>'",
  "timestamp": 1790330400000
}

403

API access is disabled for your organization (any endpoint), or, when creating an invite, your organization has no active subscription or no interview credits left.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

{
  "success": false,
  "message": "API access is not enabled for this organization",
  "timestamp": 1790330400000
}

404

The resource doesn't exist, was cancelled, or belongs to another organization. The API never returns 403 for another organization's IDs.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "success": false,
  "message": "Interview not found",
  "timestamp": 1790330400000
}

409

The interview isn't completed yet.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "success": false,
  "message": "AI analysis can only be requested for completed interviews",
  "timestamp": 1790330400000
}

429

Too many requests. Wait for Retry-After seconds (or the reset value in RateLimit), then retry.

Headers

RateLimitstring
Draft-7 rate limit state, e.g. limit=120, remaining=0, reset=42 (reset is in seconds).
RateLimit-Policystring
Draft-7 rate limit policy: the limit and the window in seconds.
Retry-Afterinteger
Seconds to wait before retrying.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "success": false,
  "message": "Too many requests. Retry after the number of seconds in the RateLimit header.",
  "timestamp": 1790330400000
}