> For the complete documentation index, see [llms.txt](https://api-docs.speechace.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.speechace.com/api-reference/score-writing.md).

# Score Writing

{% hint style="info" %}
This features requires a Premium Subscription

**Run in postman:** [Score Writing](https://docs.speechace.com/#b21cde34-7649-450a-ae0e-dabee579d1f3)
{% endhint %}

The Score Writing API evaluates 3 different writing tasks and returns scores aligned with CEFR, IELTS, PTE, and the Speechace rubrics.

<table><thead><tr><th width="142.4140625">Task</th><th width="100">Length</th><th>Description</th></tr></thead><tbody><tr><td>essay-writing</td><td>150 - 300 words</td><td>Long form opinion-based writing such as IELTS Task 2 writing prompts.</td></tr><tr><td>short-writing</td><td>50 - 100 words</td><td>Short form school or business writing such as describing an image, or writing a short letter.</td></tr><tr><td>chat-writing</td><td>50 - 100 words</td><td>Brief responses to a query or situation expressed in a chat context. Suitable for business contexts such as customer support simulation.</td></tr></tbody></table>

The Score Writing API is available in the following languages:

* English (en-us, en-gb)
* Spanish (es-es)

The Score Writing API returns scores in the following formats:

* Speechace scale (0..100)
* CEFR scale (A0..C2)
* IELTS scale (0..9)
* PTE scale (10..90)
* TOEIC scale (0..200)

### Request Format

The endpoint that is to be used will depend on the [region](/getting-started/api-regions-and-endpoints.md) of your subscription. For example, for US West, the endpoint is <https://api.speechace.co>.

`POST` [`https://api.speechace.co/api/scoring/writing/v9/json`](https://api.speechace.co/api/scoring/writing/v9/json)

### Query Parameters

<table><thead><tr><th width="136">Parameter</th><th width="117">Type</th><th>Description</th></tr></thead><tbody><tr><td>key</td><td>String</td><td><strong>Required:</strong> <em>API</em> <a href="/getting-started/authentication.md"><em>key</em></a> <em>issued by Speechace.</em></td></tr><tr><td>dialect</td><td>String</td><td><p><strong>Optional:</strong> default = en-us</p><p><em>This is the</em> <a href="/getting-started/supported-languages.md"><em>dialect</em></a> <em>in which the writing sample will be assessed.</em></p><p><em>Supported values are: <code>en-us</code>, <code>en-gb</code>, <code>es-es</code>.</em></p></td></tr><tr><td>user_id</td><td>String</td><td><em><strong>Optional</strong>: A unique anonymized identifier (generated by your applications) for the end-user who submitted the response.</em></td></tr><tr><td>task_type</td><td>String</td><td><p><em>The writing task_type to score. Supported types are:</em></p><ul><li><em>essay-writing</em></li><li><em>short-writing</em></li><li><em>chat-writing</em></li></ul></td></tr></tbody></table>

### Request Body

<table><thead><tr><th width="169">Parameter</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>prompt</td><td>String</td><td><p><strong>Required:</strong> Max 2048 chars</p><p>The writing task prompt given to the end-user.</p></td></tr><tr><td>answer</td><td>String</td><td><p><strong>Required:</strong> Max 4096 chars</p><p>The response submitted by the end-user which will be scored in context of the prompt.</p></td></tr><tr><td>include_feedback</td><td>String</td><td><p><strong>Optional:</strong> 0 | 1, default = 0<br>Indicates whether to return additional feedback also as part of the API response.</p><p><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span><strong>Warning:</strong> This field has a cost and performance impact. Use only when needed and avoid making the default on all requests.</p></td></tr><tr><td>detect_dialect</td><td>String</td><td><p><strong>Optional:</strong> 0 | 1, default = 0</p><p>Indicates whether to return detected dialect of the user response as part of of the API response.</p></td></tr><tr><td>enforce_dialect</td><td>String</td><td><p><strong>Optional:</strong> 0 | 1, default = 0</p><p>Indicates whether to enforce detected dialect of the user response be same as dialect of the calling API i.e. raises error if the user response dialect doesn't match expected dialect.</p></td></tr><tr><td>include_metrics</td><td>String</td><td><p><strong>Optional:</strong> array of string enums, default = []</p><p>Indicates which metrics to use for score. The list of enum values are: <code>vocab</code>, <code>grammar</code>, <code>coherence</code>, <code>task_response</code>. default of [] indicates all metrics to score.</p></td></tr><tr><td>score_mode</td><td>String</td><td><strong>Optional:</strong> standard | enhanced, default = "standard"<br>standard: default scoring mode (balances accuarcy, performance, and cost)<br>enhanced: enhanced scoring mode (higher accuracy model with also higher compute and cost impact)</td></tr></tbody></table>

### Request Examples

<table><thead><tr><th width="200">Example</th><th width="360">Request Parameters</th><th>When to use</th></tr></thead><tbody><tr><td>A. Essay writing</td><td><code>task_type=essay-writing</code><br><code>prompt="&#x3C;IELTS Task 2 style prompt>"</code><br><code>answer="&#x3C;150–300 word essay>"</code></td><td><em>Score a long, opinion-based essay.</em></td></tr><tr><td>B. Short writing</td><td><code>task_type=short-writing</code><br><code>prompt="&#x3C;prompt>"</code><br><code>answer="&#x3C;50–100 word response>"</code></td><td><em>Score a short school or business writing sample.</em></td></tr><tr><td>C. Chat writing</td><td><code>task_type=chat-writing</code><br><code>prompt="&#x3C;situation or query>"</code><br><code>answer="&#x3C;brief reply>"</code></td><td><em>Score a brief chat / customer-support reply.</em></td></tr></tbody></table>

{% hint style="info" %}
Add `include_feedback=1` to get detailed, per-metric feedback with suggested replacements (see the **D. Short writing + feedback** example below). It has a cost and latency impact, so enable it only when you need it.
{% endhint %}

### Response Examples

The `writing_score.speechace.overall` key contrains the overall writing score in the Speechace numerical scale (0..100). The overall score is the average of 4 sub-scores:

* `writing_score.speechace.task_response`
* `writing_score.speechace.grammar`
* `writing_score.speechace.vocab`
* `writing_score.speechace.coherence`

{% hint style="info" %}
Refer to the [Writing Score Rubric guide](/interpreting-results/interpreting-writing-scores/writing-scoring-rubrics.md) for interpreting the scores.
{% endhint %}

{% tabs %}
{% tab title="A. Essay writing" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```json
{
  "status": "success",
  "task_type": "essay-writing",
  "task_version": "0.1",
  "answer": "Some people insist that volunteer services like charity activity should be introduced to the high school curriculum, whereas others think it should not be treated as part of mandatory education. Nonetheless, I personally lean more toward the latter view, simply because the level of benefits is heavily affected by the individual point of view or circumstance.\n\nThere are several cases that unpaid service would be beneficial. For instance, they would be able to develop a sense of community or meet new people regardless of their individual skill or aptitude. According to a research paper issued by Cambridge University last year, the majority of successful people in business intentionally participate some volunteer activity at an early age in order to create connections for the future. Considering that childhood is a preparation period for a member of society, it is no doubt providing them such opportunities are more practical and fruitful idea.\n\nTurning to the other side of the argument, it could be acknowledged as a just hindrance for achieving an individual goal. Firstly, for the people who are considering to go to the university as their future plan, their top priority may not make  connections but building up academic knowledge or conquering examination. Secondly, there might be students who dedicate their time for part-time job to set aside money as a tuition fee or provide their family. From their point of view, volunteer work is just wasting their time and not necessarily essential. \n\nIn conclusion, while some people say imposing unpaid service for high school students is significant, we cannot ignore the fact that it has not only a positive aspect but also a negative side. I believe that as long as it has some drawbacks, it should not be a compulsory subject and needlessly deprive student's precious time.",
  "char_count": 1840,
  "writing_score": {
    "speechace": {
      "task_response": 78,
      "vocab": 78,
      "coherence": 78,
      "grammar": 72,
      "overall": 78
    },
    "ielts": {
      "task_response": 7,
      "vocab": 7,
      "coherence": 7,
      "grammar": 6.5,
      "overall": 7
    },
    "cefr": {
      "task_response": "B2+",
      "vocab": "B2+",
      "coherence": "B2+",
      "grammar": "B2",
      "overall": "B2+"
    },
    "pte": {
      "task_response": 66,
      "vocab": 66,
      "coherence": 66,
      "grammar": 56,
      "overall": 66
    },
    "toeic": {
      "task_response": 160,
      "vocab": 160,
      "coherence": 160,
      "grammar": 140,
      "overall": 160
    }
  },
  "version": "9.14"
}
```

{% endcode %}
{% endtab %}

{% tab title="B. Short writing" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```json
{
  "status": "success",
  "task_type": "short-writing",
  "task_version": "0.1",
  "answer": "Last week I went to Hawaii with my family.It was good,first I go to swim on the ocean it was the best of my vacations ,but then I see lots of fishes on the ocean they were beutiful and they swim so fast.My dad talk me that the fishes were so fast because they has to swim from they born and if they do not swim fast the sharks eats them.It was all beutiful and interesting.That was my best vacations of all.",
  "char_count": 407,
  "writing_score": {
    "speechace": {
      "task_response": 44,
      "vocab": 33,
      "coherence": 28,
      "grammar": 22,
      "overall": 33
    },
    "ielts": {
      "task_response": 4,
      "vocab": 3,
      "coherence": 2.5,
      "grammar": 2,
      "overall": 3
    },
    "cefr": {
      "task_response": "A2+",
      "vocab": "A2+",
      "coherence": "A2",
      "grammar": "A2",
      "overall": "A2+"
    },
    "pte": {
      "task_response": 20,
      "vocab": 15,
      "coherence": 12,
      "grammar": 10,
      "overall": 15
    },
    "toeic": {
      "task_response": 50,
      "vocab": 30,
      "coherence": 30,
      "grammar": 20,
      "overall": 30
    }
  },
  "version": "9.14"
}
```

{% endcode %}
{% endtab %}

{% tab title="C. Chat writing" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```json
{
  "status": "success",
  "task_type": "chat-writing",
  "task_version": "0.1",
  "answer": "I am really sorry to hear about your experience. Let me help you address this right away. I will need your order details and a description of the damage, and then I will immediately send you a replacement item. If you prefer a refund, please let me know. Finally, we will also send you instructions on how to return the damaged item.\nWe apologize for this experience and hope to immediately rectify it.",
  "char_count": 402,
  "writing_score": {
    "speechace": {
      "task_response": 78,
      "vocab": 78,
      "coherence": 83,
      "grammar": 78,
      "overall": 83
    },
    "ielts": {
      "task_response": 7,
      "vocab": 7,
      "coherence": 7.5,
      "grammar": 7,
      "overall": 7.5
    },
    "cefr": {
      "task_response": "B2+",
      "vocab": "B2+",
      "coherence": "C1",
      "grammar": "B2+",
      "overall": "C1"
    },
    "pte": {
      "task_response": 66,
      "vocab": 66,
      "coherence": 76,
      "grammar": 66,
      "overall": 76
    },
    "toeic": {
      "task_response": 160,
      "vocab": 160,
      "coherence": 170,
      "grammar": 160,
      "overall": 170
    }
  },
  "version": "9.14"
}
```

{% endcode %}
{% endtab %}

{% tab title="D. Short writing + feedback" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```json
{
  "status": "success",
  "task_type": "short-writing",
  "task_version": "0.1",
  "answer": "Last week I went to Hawaii with my family.It was good,first I go to swim on the ocean it was the best of my vacations ,but then I see lots of fishes on the ocean they were beutiful and they swim so fast.My dad talk me that the fishes were so fast because they has to swim from they born and if they do not swim fast the sharks eats them.It was all beutiful and interesting.That was my best vacations of all.",
  "char_count": 407,
  "writing_score": {
    "speechace": {
      "task_response": 44,
      "vocab": 28,
      "coherence": 28,
      "grammar": 22,
      "overall": 33
    },
    "ielts": {
      "task_response": 4,
      "vocab": 2.5,
      "coherence": 2.5,
      "grammar": 2,
      "overall": 3
    },
    "cefr": {
      "task_response": "A2+",
      "vocab": "A2",
      "coherence": "A2",
      "grammar": "A2",
      "overall": "A2+"
    },
    "pte": {
      "task_response": 20,
      "vocab": 12,
      "coherence": 12,
      "grammar": 10,
      "overall": 15
    },
    "toeic": {
      "task_response": 50,
      "vocab": 30,
      "coherence": 30,
      "grammar": 20,
      "overall": 30
    }
  },
  "feedback": {
    "vocab": [
      {
        "category": "Redundancy and Tautology",
        "original_phrase": "first I go to swim on the ocean",
        "replacement_phrase": "first I went swimming in the ocean",
        "rationale": "Avoid redundancy and use a more concise and accurate phrase.",
        "span": [
          54,
          84
        ],
        "replacements": [
          {
            "span": [
              62,
              73
            ],
            "text": "go to swim o",
            "type": "omission"
          },
          "... (1 more)"
        ]
      },
      "... (6 more)"
    ],
    "coherence": [
      {
        "category": "Logical Progression of Ideas",
        "original_phrase": "first I go to swim on the ocean it was the best of my vacations ,but then I see lots of fishes on the ocean they were beutiful and they swim so fast.",
        "replacement_phrase": "First, I went swimming in the ocean. It was the highlight of my vacation. I saw many beautiful and fast-swimming fishes.",
        "rationale": "The revised sentence provides a clearer and more organized sequence of events, improving the logical progression of ideas.",
        "span": [
          54,
          202
        ],
        "replacements": [
          {
            "span": [
              54,
              54
            ],
            "text": "f",
            "type": "omission"
          },
          "... (13 more)"
        ]
      },
      "... (2 more)"
    ],
    "grammar": [
      {
        "category": "Subject-Verb Agreement",
        "original_phrase": "first I go to swim on the ocean",
        "replacement_phrase": "first I went swimming in the ocean",
        "rationale": "Subject-verb agreement between 'I' and 'went'",
        "span": [
          54,
          84
        ],
        "replacements": [
          {
            "span": [
              62,
              73
            ],
            "text": "go to swim o",
            "type": "omission"
          },
          "... (1 more)"
        ]
      },
      "... (5 more)"
    ]
  },
  "version": "9.14"
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Which writing task\_type should I use?**

Here is when to use each task\_type:

If the writing is an essay and at least 150 words, then use essay-writing. If it's general and less than 150 words, then use short-writing. If the prompt contains a chat scenario with the user expected to respond to a question or situation, then use chat-writing.
{% endhint %}