# RevCent API Calls Overview

This document explains API Calls in RevCent: what they are, how RevCent records them, how to understand the source of an API call, when to use `GetAPICall`, and why `BigQueryRunQuery` should be used when retrieving lists, searching, reporting, metrics, or auditing many API calls.

This is not a single operation guide. It is a broad overview of API Calls as a RevCent system capability.

Sources:
- RevCent MCP/API schema for `GetAPICall`
- RevCent MCP/API schema guidance for `BigQueryRunQuery`
- RevCent MCP/API schema guidance for `GetBigQueryTables`

---

# What Is an API Call in RevCent?

An API Call is a RevCent record of an operation/request that occurred in the RevCent system.

RevCent records API calls so users, MCP clients, AI workflows, developers, support teams, and auditors can understand:

```text
What operation happened.
When it happened.
Whether it succeeded or failed.
What system or user source initiated it.
What request was sent.
What response was returned.
What related RevCent items were affected.
Whether the call happened in live mode or test mode.
Whether the call came from an API account, web app user, third-party shop, AI Assistant, AI Voice Agent, system process, webhook, or other source context.
```

API Calls are important because they provide an operational history of activity inside RevCent.

---

# Why RevCent Records API Calls

RevCent records API Calls for visibility, debugging, auditing, and reporting.

API Call records help answer questions such as:

```text
Who or what created this sale?
Was this refund created by a user, API account, AI Assistant, or AI Voice Agent?
What request payload was used?
What response did RevCent return?
Did an API action succeed or fail?
Which customer, sale, transaction, refund, subscription, shipment, or chargeback was affected?
How many times did this integration call an operation?
Which third-party shop created the most API activity?
Which AI Assistant or AI Voice Agent performed a system action?
Which API calls failed in the last 24 hours?
```

For ecommerce businesses, API Calls are useful for:

```text
Debugging checkout issues.
Auditing payment attempts.
Monitoring third-party shop integrations.
Auditing AI Assistant and AI Voice Agent actions.
Tracking refund and chargeback workflows.
Finding failed API operations.
Measuring automation activity.
Understanding source attribution.
Investigating customer support issues.
Reconciling related records.
```

---

# API Call Sources

A key purpose of API Calls is understanding the source of an operation.

API Calls may originate from several sources.

The single-call `GetAPICall` response can expose fields such as:

```text
api_account
ip_address
is_web_app
is_system
is_webhook
live_mode
third_party_shop
web_user
metadata
```

The BigQuery `api_call` table can expose source-related fields such as:

```text
api_account
ai_assistant
ai_voice_agent
ai_voice_call
is_system
is_third_party_shop
third_party_shop
is_web_app
user
live_mode
metadata
```

These fields help identify who or what performed the action.

---

## API Account Source

If an API call was made through a RevCent API account, the record may include:

```text
api_account.id
api_account.name
```

Use this to answer:

```text
Which API account made this call?
Was this operation performed by a production integration?
Was this request made by a known API account?
Which integration is generating failed calls?
```

Example use case:

```text
A checkout integration is returning errors.
Query API calls by api_account and code to find failure patterns.
```

---

## Web App Source

If an API call was made from the RevCent web app, source fields may indicate that it came from a logged-in user.

Single-call detail may include:

```text
is_web_app
web_user.id
web_user.username
```

BigQuery may include:

```text
is_web_app
user
```

Use this to answer:

```text
Was this action performed by a logged-in RevCent user?
Which web user performed the action?
Was a refund created manually in the web app?
Was a note or chargeback created by an internal user?
```

---

## System Source

If an API call was created by the RevCent system, it may include:

```text
is_system = true
```

Use this to identify system-generated actions.

Examples:

```text
Internal automation.
System-created records.
Automated background processes.
Internal orchestration.
```

---

## Webhook Source

`GetAPICall` can expose:

```text
is_webhook
```

This helps identify calls made by an internal webhook pathway.

Use this when investigating webhook-driven workflows or system-generated integration activity.

---

## Third-Party Shop Source

API Calls may be associated with a third-party shop.

Fields can include:

```text
third_party_shop.id
third_party_shop.name
is_third_party_shop
```

Use this to answer:

```text
Did this call originate from a third-party shop?
Which shop/storefront created the sale or payment?
Which third-party shop integration is generating failed calls?
How much API activity comes from each shop?
```

This is especially useful for ecommerce businesses with:

```text
Multiple stores.
Multiple domains.
Multiple shopping cart integrations.
Multiple brands.
Multiple external storefronts.
```

---

## AI Assistant Source

The BigQuery `api_call` table can include:

```text
api_call.ai_assistant
```

This allows reporting on API calls made by or associated with an AI Assistant.

Use this to answer:

```text
Which AI Assistant created notes?
Which AI Assistant inserted metadata?
Which AI Assistant sent emails?
Which AI Assistant triggered Functions?
Which AI Assistant attempted payment/refund actions?
Which AI Assistant had API failures?
```

This is especially important for revenue-focused AI Assistants that analyze sales, recover declines, trigger emails, create notes, insert metadata, or perform other system actions.

---

## AI Voice Agent and AI Voice Call Source

The BigQuery `api_call` table can include:

```text
api_call.ai_voice_agent
api_call.ai_voice_call
```

Use this to report on API calls performed by AI Voice Agents or tied to specific AI Voice Calls.

Examples:

```text
Which voice agents attempted payment actions?
Which calls created notes or inserted metadata?
Which calls triggered Functions?
Which calls attempted refunds?
Which calls had failed API actions?
```

This is valuable for measuring AI Voice Agent performance and auditing high-impact call actions.

---

# Single API Call Retrieval: Use `GetAPICall`

When the user wants the details of one specific API Call, use:

```text
GetAPICall
```

`GetAPICall` requires:

```text
api_call_id
```

Example request:

```json
{
  "api_call_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

Use `GetAPICall` when:

```text
The API call ID is known.
The user wants the raw request and response.
The user wants to debug one API call.
The user wants to see source details for one call.
The user wants related item IDs for one call.
The user wants to inspect the result of one operation.
```

---

# `GetAPICall` Input

| Field | Type | Required | Description |
|---|---:|---:|---|
| `api_call_id` | string | Yes | 20-character API Call ID. |

Do not guess API Call IDs.

If the ID is unknown and the user wants to find matching calls, use BigQuery against the `api_call` table.

---

# `GetAPICall` Response Capabilities

`GetAPICall` can return detailed information such as:

| Field | Meaning |
|---|---|
| `id` | API Call ID. |
| `created_date_unix` | When the API Call was created. |
| `type` | API call type. |
| `method` | API call method. |
| `api_account` | API account associated with the call. |
| `ip_address` | IP address that made the API call. |
| `request` | Raw request JSON object. |
| `response` | Raw response JSON object. |
| `result` | API call result message. |
| `is_web_app` | Whether the call was made by a user in the RevCent web app. |
| `is_system` | Whether the call was made by the RevCent system. |
| `is_webhook` | Whether the call was made by an internal webhook. |
| `live_mode` | Whether the call used Live or Test mode. |
| `metadata` | Metadata name/value pairs on the API Call. |
| `third_party_shop` | Originating user shop, if applicable. |
| `web_user` | Originating web user, if applicable. |
| related item arrays | IDs of related RevCent records. |

---

# Raw Request and Response

One of the main reasons to use `GetAPICall` is to inspect:

```text
request
response
```

These fields help with debugging.

Examples:

```text
Why did a sale creation fail?
What did the API client send?
What error did RevCent return?
What fields were missing?
What item IDs were returned?
Was the call made in live mode or test mode?
```

Important:

```text
Use GetAPICall for detailed inspection of one known API call.
Use BigQueryRunQuery for searching or listing many API calls.
```

---

# Related Item IDs

`GetAPICall` can return arrays of related item IDs.

Examples include:

```text
sales
product_sales
shipping
tax
discounts
trials
subscriptions
subscription_renewals
invoices
license_keys
transactions
ai_threads
ai_assistants
paypal_transactions
offline_payments
check_directs
salvage_transactions
pending_refunds
chargebacks
fraud_detections
api_calls
```

These related IDs help MCP/AI retrieve the affected RevCent records.

Examples:

```text
If `sales` contains IDs, retrieve sale details with GetSale.
If `transactions` contains IDs, retrieve transaction details with GetTransaction.
If `pending_refunds` contains IDs, retrieve refund details with GetPendingRefund.
If `ai_threads` contains IDs, retrieve AI Thread details with GetAIThread.
If `chargebacks` contains IDs, retrieve chargeback details with GetChargeback.
```

This makes API Calls useful as a bridge to related business records.

---

# Listing, Searching, and Reporting API Calls: Use BigQueryRunQuery

When the user wants to retrieve a list of API Calls, search across API Calls, or run reports, use:

```text
BigQueryRunQuery
```

Query the API Call table:

```sql
`revcent.user.api_call`
```

Use BigQuery for:

```text
Lists of API Calls.
Searches across API Calls.
Counts.
Aggregations.
Metrics.
Data mining.
Audits.
Dashboards.
Failed call reports.
Source attribution reports.
AI Assistant action reports.
AI Voice Agent action reports.
Third-party shop activity reports.
API account activity reports.
Revenue-related action reports.
```

---

# Why BigQuery Should Be Used for API Call Lists

RevCent records many API Calls.

Because API Calls can be created by:

```text
API integrations.
Web app users.
System processes.
Webhooks.
Third-party shops.
AI Assistants.
AI Voice Agents.
Customer-facing workflows.
Payment and refund operations.
```

the API Call dataset can grow quickly.

Therefore, when retrieving API Calls with BigQuery:

```text
Apply filters.
Use date ranges.
Select only needed fields.
Use LIMIT when exploring.
Group or aggregate where appropriate.
Avoid SELECT * for large searches.
```

Unfiltered API Call queries may return too much data or take too long.

`BigQueryRunQuery` has a 30-second query runtime limit, so filtering is important.

---

# Recommended API Call BigQuery Filters

Useful filters include:

```text
Date/time range
API call type
API call method
Response code
API account
Live/test mode
Web app source
System source
Third-party shop source
AI Assistant ID
AI Voice Agent ID
AI Voice Call ID
Metadata name/value
```

Common examples:

```text
Only failed calls in the last 24 hours.
Only sale creation calls from one API account.
Only calls created by AI Assistants.
Only calls tied to a specific AI Voice Call.
Only calls from a third-party shop.
Only refund-related calls in live mode.
```

---

# BigQuery Rules

When using `BigQueryRunQuery`:

```text
Use BigQuery Standard SQL.
Use fully qualified table references.
Wrap table names in backticks.
Use `revcent` as project ID.
Use `user` as dataset ID.
Use GetBigQueryTables before writing queries.
Avoid COALESCE.
When using TIMESTAMP_SUB, only use INTERVAL in DAY.
Optimize queries to avoid 30-second timeouts.
```

Correct table reference:

```sql
`revcent.user.api_call`
```

---

# Use GetBigQueryTables First

Before writing production SQL, MCP/AI should call:

```text
GetBigQueryTables
```

This confirms:

```text
Available tables.
Exact field names.
Data types.
Join paths.
Metadata structure.
Whether a desired field exists.
```

MCP/AI should not guess table names or fields when writing final reports.

---

# Common BigQuery API Call Fields

The `api_call` table can include fields such as:

| Field | Meaning |
|---|---|
| `created_at` | Timestamp when the API Call was created. |
| `id` | API Call ID. |
| `type` | API call type. |
| `method` | API call method. |
| `code` | API call response code. |
| `live_mode` | Whether the call was live or test mode. |
| `is_system` | Whether the call was made by the internal system. |
| `is_third_party_shop` | Whether the call was made from a third-party shop. |
| `third_party_shop` | Third-party shop ID. |
| `api_account` | API account ID. |
| `ai_assistant` | AI Assistant ID if associated with an AI Assistant. |
| `ai_voice_agent` | AI Voice Agent ID if associated with an AI Voice Agent. |
| `ai_voice_call` | AI Voice Call ID if associated with a specific AI Voice Call. |
| `is_web_app` | Whether the call was made from the web app. |
| `user` | Web user ID, when applicable. |
| `metadata` | Repeated metadata name/value entries. |

---

# Example: Recent API Calls

Use a date filter and a limit.

```sql
SELECT
  created_at,
  id,
  type,
  method,
  code,
  live_mode,
  api_account,
  is_web_app,
  is_system,
  is_third_party_shop
FROM `revcent.user.api_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
ORDER BY created_at DESC
LIMIT 100
```

---

# Example: Failed API Calls in the Last 24 Hours

```sql
SELECT
  created_at,
  id,
  type,
  method,
  code,
  api_account,
  is_web_app,
  is_system,
  third_party_shop,
  ai_assistant,
  ai_voice_agent,
  ai_voice_call
FROM `revcent.user.api_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
  AND code != 1
ORDER BY created_at DESC
LIMIT 100
```

Use `GetAPICall` on a returned `id` to inspect the raw request/response.

---

# Example: API Calls by Type and Method

```sql
SELECT
  type,
  method,
  COUNT(*) AS api_call_count,
  SUM(IF(code = 1, 1, 0)) AS success_count,
  SUM(IF(code != 1, 1, 0)) AS failure_count,
  ROUND(SUM(IF(code = 1, 1, 0)) * 100.0 / COUNT(*), 2) AS success_rate_percent
FROM `revcent.user.api_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY type, method
ORDER BY api_call_count DESC
```

This helps identify high-volume operations and failure patterns.

---

# Example: API Calls by Source

```sql
SELECT
  CASE
    WHEN ai_voice_call IS NOT NULL THEN 'ai_voice_call'
    WHEN ai_voice_agent IS NOT NULL THEN 'ai_voice_agent'
    WHEN ai_assistant IS NOT NULL THEN 'ai_assistant'
    WHEN is_third_party_shop THEN 'third_party_shop'
    WHEN is_web_app THEN 'web_app'
    WHEN is_system THEN 'system'
    WHEN api_account IS NOT NULL THEN 'api_account'
    ELSE 'unknown'
  END AS api_call_source,
  COUNT(*) AS api_call_count,
  SUM(IF(code = 1, 1, 0)) AS success_count,
  SUM(IF(code != 1, 1, 0)) AS failure_count
FROM `revcent.user.api_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY api_call_source
ORDER BY api_call_count DESC
```

This helps understand where API activity is coming from.

---

# Example: API Calls by API Account

```sql
SELECT
  api_account,
  type,
  method,
  COUNT(*) AS api_call_count,
  SUM(IF(code = 1, 1, 0)) AS success_count,
  SUM(IF(code != 1, 1, 0)) AS failure_count
FROM `revcent.user.api_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  AND api_account IS NOT NULL
GROUP BY api_account, type, method
ORDER BY api_call_count DESC
```

Use this for integration monitoring.

---

# Example: API Calls by Third-Party Shop

```sql
SELECT
  third_party_shop,
  type,
  method,
  COUNT(*) AS api_call_count,
  SUM(IF(code = 1, 1, 0)) AS success_count,
  SUM(IF(code != 1, 1, 0)) AS failure_count
FROM `revcent.user.api_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  AND third_party_shop IS NOT NULL
GROUP BY third_party_shop, type, method
ORDER BY api_call_count DESC
```

Use this to monitor shop/storefront integration activity.

---

# Example: AI Assistant API Activity

```sql
SELECT
  ai_assistant,
  type,
  method,
  COUNT(*) AS api_call_count,
  SUM(IF(code = 1, 1, 0)) AS success_count,
  SUM(IF(code != 1, 1, 0)) AS failure_count
FROM `revcent.user.api_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  AND ai_assistant IS NOT NULL
GROUP BY ai_assistant, type, method
ORDER BY api_call_count DESC
```

This helps measure what AI Assistants are doing.

---

# Example: AI Voice Agent API Activity

```sql
SELECT
  ai_voice_agent,
  ai_voice_call,
  type,
  method,
  COUNT(*) AS api_call_count,
  SUM(IF(code = 1, 1, 0)) AS success_count,
  SUM(IF(code != 1, 1, 0)) AS failure_count
FROM `revcent.user.api_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  AND ai_voice_agent IS NOT NULL
GROUP BY ai_voice_agent, ai_voice_call, type, method
ORDER BY api_call_count DESC
```

This helps measure AI Voice Agent system actions and call-specific actions.

---

# Example: Payment, Refund, and Revenue-Related API Calls

Use keyword matching to explore payment-related actions.

MCP/AI should refine this after discovering exact `type` and `method` values in the account.

```sql
SELECT
  type,
  method,
  COUNT(*) AS action_count,
  SUM(IF(code = 1, 1, 0)) AS success_count,
  SUM(IF(code != 1, 1, 0)) AS failure_count
FROM `revcent.user.api_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  AND REGEXP_CONTAINS(
    LOWER(CONCAT(type, ' ', method)),
    r'sale|payment|transaction|refund|void|card|pending|renew'
  )
GROUP BY type, method
ORDER BY action_count DESC
```

Useful for:

```text
Sale creation monitoring.
Payment attempt reporting.
Refund action reporting.
Subscription renewal action reporting.
Card add/update action monitoring.
Revenue workflow analysis.
```

---

# Example: Metadata Filtering

Because API Calls can have metadata, BigQuery can search metadata entries.

Example:

```sql
SELECT
  ac.created_at,
  ac.id,
  ac.type,
  ac.method,
  ac.code,
  m.name AS metadata_name,
  m.value AS metadata_value
FROM `revcent.user.api_call` ac,
UNNEST(ac.metadata) AS m
WHERE ac.created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
  AND m.name = 'workflow'
  AND m.value = 'declined_sale_recovery'
ORDER BY ac.created_at DESC
LIMIT 100
```

Use metadata filters when workflows intentionally tag API Calls.

---

# When to Use GetAPICall vs BigQueryRunQuery

| User Goal | Correct Tool |
|---|---|
| Retrieve one known API Call by ID | `GetAPICall` |
| Inspect raw request/response for one call | `GetAPICall` |
| Find recent API calls | `BigQueryRunQuery` |
| Search API calls by type/method/source/status | `BigQueryRunQuery` |
| Count API calls | `BigQueryRunQuery` |
| Report API calls by source | `BigQueryRunQuery` |
| Report API call success/failure rates | `BigQueryRunQuery` |
| Analyze AI Assistant or AI Voice Agent API actions | `BigQueryRunQuery` |
| Analyze payment/refund/revenue-related API actions | `BigQueryRunQuery` |
| Data mining or audits across many calls | `BigQueryRunQuery` |

---

# Practical Ecommerce Use Cases

## Checkout Debugging

```text
Find failed sale creation API calls.
Inspect one failed call with GetAPICall.
Review the request/response to identify the issue.
```

## Payment Monitoring

```text
Report payment-related API call success/failure rates.
Identify high failure periods.
Review specific failed API calls.
```

## Refund Auditing

```text
Search refund-related API calls.
Group by source, user, AI Assistant, AI Voice Agent, or API account.
Retrieve one refund API call for raw request/response details.
```

## AI Assistant Auditing

```text
Report which AI Assistants created notes, inserted metadata, triggered Functions, sent emails, or performed revenue-related actions.
```

## AI Voice Agent Auditing

```text
Report which AI Voice Agents attempted payment actions, created notes, inserted metadata, triggered Functions, or issued refunds during calls.
```

## Third-Party Shop Monitoring

```text
Report API call volume and failures by third-party shop.
Find shop integrations causing errors.
```

## Web User Accountability

```text
Investigate which logged-in user performed a specific web app action.
Retrieve the API call and review web_user/source context.
```

## System and Webhook Monitoring

```text
Analyze system-created or webhook-created API activity.
Identify unexpected error spikes.
```

---

# Security and Sensitive Data

API Call details may include raw request and response objects.

MCP/AI should treat these carefully.

Do not expose sensitive values unnecessarily.

Be especially careful with:

```text
Payment-related request data.
Customer personal information.
API credentials.
Tokens.
Secrets.
Private integration data.
Raw response payloads that include sensitive fields.
```

When summarizing API calls for users:

```text
Show relevant operational facts.
Avoid exposing secrets.
Avoid displaying raw sensitive payment data.
Use concise summaries unless the user specifically needs raw debugging details.
```

---

# MCP/AI Guidance

When the user asks about API Calls:

1. Determine whether the user wants one known API Call or a list/report.
2. If the user provides an `api_call_id`, use `GetAPICall`.
3. If the user wants to find API Calls, use `BigQueryRunQuery`.
4. If the user wants metrics/reporting/data mining/audits, use `BigQueryRunQuery`.
5. Use `GetBigQueryTables` before writing final BigQuery SQL.
6. Apply filters because many API Calls are recorded.
7. Prefer date filters whenever possible.
8. Use `LIMIT` when exploring.
9. Use `GetAPICall` on a returned BigQuery `id` for raw request/response detail.
10. Use source fields to identify whether a call came from API account, web app, system, webhook, third-party shop, AI Assistant, AI Voice Agent, or AI Voice Call.
11. Use related item IDs from `GetAPICall` to retrieve affected records.
12. Avoid exposing sensitive request/response data unnecessarily.

---

# Common Mistakes

## Mistake: Looking for a `GetAPICalls` List Operation

Wrong:

```text
Try to retrieve a list of API Calls using a paginated API operation.
```

Correct:

```text
Use BigQueryRunQuery against `revcent.user.api_call`.
```

## Mistake: Querying API Calls Without Filters

Wrong:

```sql
SELECT * FROM `revcent.user.api_call`
```

Correct:

```sql
SELECT
  created_at,
  id,
  type,
  method,
  code
FROM `revcent.user.api_call`
WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
ORDER BY created_at DESC
LIMIT 100
```

## Mistake: Using BigQuery When Raw Request/Response Is Needed for One Call

Wrong:

```text
Only query the api_call table when the user needs raw request/response details for one call.
```

Correct:

```text
Use BigQuery to find the API Call ID, then use GetAPICall to retrieve the single detailed record.
```

## Mistake: Ignoring Source Fields

Wrong:

```text
Only look at type/method/code.
```

Better:

```text
Also review source fields such as api_account, is_web_app, is_system, third_party_shop, ai_assistant, ai_voice_agent, and ai_voice_call.
```

---

# Key Takeaways

```text
RevCent records API Calls so users can debug, audit, monitor, and report on system activity.
```

```text
Use GetAPICall when retrieving one specific API Call by ID.
```

```text
Use BigQueryRunQuery against `revcent.user.api_call` when retrieving lists, searching, reporting, running metrics, auditing, or data mining API Calls.
```

```text
Apply filters when querying API Calls because many API Calls are recorded.
```

```text
Use GetBigQueryTables before writing production BigQuery SQL.
```

```text
API Call source fields can identify whether activity came from API accounts, web app users, system processes, webhooks, third-party shops, AI Assistants, AI Voice Agents, or AI Voice Calls.
```

```text
Use GetAPICall to inspect raw request/response data for one call after finding its ID through BigQuery.
```

Used correctly, API Calls give ecommerce businesses a powerful audit and observability layer for RevCent operations, integrations, AI automation, payment workflows, refunds, customer support, and system health.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.